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INTRODUCTION 


‘The Mbt. language is described in “The Moi. Programming ! anguage" {3}. but in addition w the language 
ltsolf, there is a rich and varied collection of software written in the language which facilitates the writing of 
programs and systems of programs in Mbt. ‘The information describing this programming environment has 
been contained in various documents. some out of print or out of date, and in supplemental disk files 
describing changes and additions. Some of the packages of functions used tw deal with Min. code have never 
boen formally documented. ‘This manual brings together some of that scattered documentation. 


“The document's purpose is to Mesh out the description of the language contained in “The MDL 
Programming {anguage.’ giving a fuller description of the program writing and debugging aids available to 
MDI. users, to describe the methods for producing cade usable by others, wo describe the Mit compiler and. 
the many other techniques fur producing and speeding up MDI. object code, 


‘The imagined reader uf this document is someone who has read “Ihe MDI. Programming |_anguage.” and 
now proposes to write programs in MDL. possibly even very large programs. Mbt, packages that he would 
find useful in the process of doing so are documented here: editors, debuggers, etc. Packages that he might 
wish to use within his program are not included: data-management systems, command interpreters, etc. 


‘This document is of necessity highly sclf-referent, as many of the components of the MDI programming. 
cavironment refer to cach other and adhere to the same conventions. Additionally, this document assumes 
that the reader is familiar with the language itsolf (at least to some degree) and with the ITS, ‘TENEX, or 
VOPS-20 operating systems. 
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NOTATION 


Anything which is written inthe Mi. language or which is typed on a computer console appears hercin in 
‘typewriter font, as in PPRINT. A metasyntactic variuble -- something to be replaced in actual use by: 
something else -- appears as channel, in an italic font. Where a meta-syntactic variable is being used to denote 
4 required argument to some function, it sppcars as before. but underlined, as channel. 


In the argument templates of Mbt. functions, the individual arguments are often given in the form 
argumentziype, where argument is a descriptive’ name for the argument, and ype is its MD! type (or range of 
Iypes). In such eases, the “type” boolean indicates an argument that is only examined for truth or falsity. and 


not for any of its other qualities. Such arguments in Mbi. are often declared "<OR ATOM FALSE>’. 


¥y. file names are given as though for the I'S operating system: 
device: sname:funt fum2 
‘The analogous specification for'TENEX or TOPS-20 would be 
device: <sname>funt .fum2 
Note that in the 'TENEX/TOPS-20 version of Mp1, the fiun2 (which may include the generation number, 
protection and accc-nt fields) is by default "MUD™ as opposed to ">" for the ITS version. 


NOTATION 
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1. Overview of the MDL Programming 
Environment 
‘The parts of the MPI. programming environment described in this document are primarily those dealing 
with the writing, debugging, sharing, and maintenance of code and programs written in Mbt, Most of the 
packages described herein are written in MDI themselves: some are assembly language programs useful to 
MDI programmers, 


‘The document is divided into chapters dealing with the major issues facing the novice (or even the 
experienced) MDI. programmer. 


~ “Whe Package System’ introduces the standard mechanism for lexical blocking and therefore, 
sharing of Mit. code. Understanding its use is fundamental to writing MD1. programs. 


= ‘Program Writing and Debugging Aids is the largest chapter. It covers mechanisms fur loading, 
dumping, cditing, and debugging Mb. code, whether interpreted or compiled. in a development 
‘or. production environment. 


= “The Library System’ discusses the usage of libraries of MDI. programs. 


— “The Compiler’ includes the specifics of interaction with the MI. compiler, as well as an overview 
of the theory behind its operation. 


‘Making It Run Faster’ covers the various methods fur speeding up ‘production’ Mpi. code by 
removing mediated calls and compacting data structures. 


— "The Assembler’ documents the MDI assembler and some methods of debugging binary code, 


~ ‘Informational Aids’ discusses a few programs, most written in assembly language rather than 
MDL, which are useful wo the MDI. programmer, 


oe 
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2. The Package System 
‘The portion of the Mt environment which provides a uniform facility for lexical blocking is known as the 
Package System. In one sense it is the most basic part of the environment, since it cnables many programmers: 


to use cach other's code without identifier conflicts. 


In addition, the Package System is interfaced to a library facMlity (see section 4) by which MII. code may 
be stored und later loaded as needed. 


‘The Package System is so basic to use of the MDI. environment that (with a few exceptions) every 
subsystem ur family of MDI. functions described in this document is a ‘package’. 


2.1. The Theory of Lexical Blocking in MDL 

Lexical blocking is implemented in MDI by means of OBLISTs and LISTs of OBLISTs. Changes of 
lexical context are performed using the SUBRs BLOCK and ENDBLOCK. ‘The Package System provides a 
high-level interface to these low-level constructs. 


‘The primary goal of a lexical blocking scheme is the prevention of identifier conflicts. Specifically, when 
your program references the variable X, it should be your X und not that of some other program. At the same 
time, it should not be necessary fora programmer to scarch every program previously written to verify that an 
identifier he wishes to use is not already ‘taken’. 


It should be clear that the simplest solution, a single OBLIST, will not satisfy cither of these goals. With 
only one OBLIST there would necessarily be identifier conflicts. necessitating exhaustive searching for unique 
identifiers. 


Obviously, programmers could put their program's identifiers on an OBLIST unique to that program. 
Unfortunately, such a solution addresses only half the problem, What happens when some other programmer 
wishes to use some of this code? He could insert the unique OBLIST for that program into the OBLIST path 
for his program: but the moment that is done he gets all the identifiers for that program, including local 
variables, internal data structures, and so on, 


Consequently, we move toa situation where cach program uses two OBLISTs: one for the identifiers that 
are local to the program, and one for the identifiers that are to be used by other programs. In the Package 
System, these are known as the “internal” OBLIST and the ‘entry’ OBLIST, 


Most of the identifiers in a program are local to it, and want to be placed on the internal OBLIST. 


20 
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Therefore, in terms of an argument to the BLOCK SUBR, when a program is being loaded into MP, the 
OBLIST path wants to be: 


(_ internal-oblist 
entry-oblist 
<ROOT> ) 


With this OBLIST path, most ATOMs (identifiers) will be on the internal OBLIST (as READ puts unknown 


identifiers on <1 .OBLIST>), but the ATOMS fur the entries and the ATOMS for the usual SUBRs will be 
wailable, 


“The only issue yet to be addressed is that of using an entry of a different program in your program. ‘This is 
uccomplished by adding the entry OBLISTs of any such programs to the path after ROOT: 


( fmternal-oblist 
entry-oblist 
<ROOT> 
other program-entry-oblist 
set-another program-entry-oblist 


) 


‘As only the entry OBLIST, and not the internal OBLIST, of the program being used is added to the path, 
the chance of identifier conflict is lessened. 


All that remains is to introduce the functions by which these various operations are performed. 


2.2. Package System Overview 
‘The functions which make up the Package System are: 


— PACKAGE. ‘This indicates the start of a package of functions. 
— ENDPACKAGE. ‘This indicates the end of the package of functions, 


— ENTRY. ‘This indicates an ATOM which is to be made available outside the definition of this 
package of functions. All other ATOMS will not be directly available outside the package. 


— USE. This indicates a reference by name to another package of functions, 
— USE-DATUM. This indicates a reference by name wo a data set 


— DROP and L-UNUSE. ‘These undo the effects of USE and USE-DATUM. 


‘These functions are themselves part of'a package named PKG”, which is preloaded into MDL. 
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2.2.1, Sample PACKAGE 


A sample MDI, PACKAGE is given with comments in order to demonstrate the usage of these functions. 
<PACKAGE "HOUR-STRING™> 


"PACKAGE begins the package called HOUR-STRING.” 
<ENTRY TIME-STRING> 
s"The atom TIME-STRING is an entry to this pack: 


it may be referenced by other packages by 
USE ing HOUR-STRING.* 


<USE "DATIME"> 


"Indicate that the package DATIME is 
used within the current package." 


<DEFINE TIME-STRING () 
<STRING <UNPARSE <HOURS>> * o‘clock">> 


i"Define this little function which returns a string 
telling the last hour in @ strange format.” 


<DEFINE HOURS () <1 <RTIME>>> 


;"Define an internal function which is available 
only within the HOUR-STRING package, since its 
name is not in any ENTRY statement. 

Note that this function refers to RTIME, 

which is an ENTRY in the DATIME package.” 


<ENDPACKAGE> 


"The end of this little demonstration package.” 


2.3. PACKAGE 

“This function delimits the beginning of a package of functions. It takes one required argument, a STRING, 
which is the name of the package, ‘This STRING uniquely identifies the package within a library of packages 
(see section 4). 


In @ PACKAGE those ATOMs which are specified as enirics live in a separate OBLIST of their own, called 
the entry OBLIST. ‘The ATOM naming this OBLIST is on the PACKAGE OBLIST and has the sume name as 
the PACKAGE itself. ‘Thus. an entry.“X” of a PACKAGE “Y” would have as its “full-trailer’ name: 
XI-YI-PACKAGE!~ 


PACKAGE blocks (sets up) the current OBLIST path so that the ATOMs which are internal wo the PACKAGE 
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{fall into an OBLIST which is not otherwise used. The ATOM nauning this OBLIST is on the cntry OBLIST of 
the PACKAGE, and is by default given a name created by putting the character “1° at the beginning of the 
PACKAGE's name. An intemal ATOM "Z° in the PACKAGE “Y” previously mentioned would have as its 
“full-trailer’ name: 21-1Y}~¥!-PACKAGE! - 


PACKAGE also keeps track of the fact that the particular PACKAGE named has been defined in this MOL 
process. by putting its name un the PACKAGE OBLIST. 
<PACKAGE jome:siring 
iname:string 
sizesfix 
isizesfix> 


PACKAGE tikes three optional arguments in addition to the required one (the optional arguments are 
ignored if name is already a PACKAGE): 


fname ts the name of the internal OBL TST of the PACKAGE; by default it is the name of the PACKAGE with 
the letter “I” prefixed. 


size is the number of buckets in the entry oblist; by default 19, 


size is the number of buckets in the internal oblist: by default 23. 


In addition to PACKAGE, there exists the obsolete function RPACKAGE. documented here only because 
suine programs still use it. ‘The difference between them is that the entry OBLIST for an RPACKAGE is the 
ROOT OBLIST. ‘The implication of inserting an entry imto the ROOT is that this requires that the name of the 
eniry be unique over all PACKAGES, because the entry is, in effect, being promoted to the status aa SUBR. It 
{s (in rare cases) useful to do this, but the correct way is with the function RENTRY (sce section 2.3.1). 


3.1. ENTRY 

‘The ENTRY function applied w one or more ATOMS declares thut these ATOMS are to be put into the 
OBL IST reserved for entries in this particular PACKAGE. Only ATOMs declared in this way will be accessible 
(in the normal course of events) w Functions outside this PACKAGE. 


Icis possible to place some entries of a PACKAGE on the ROOT OBLIST using the function RENTRY. It is 
recominended that instead of using RPACKAGE in those rare cases where entries must go on the ROOT. 
RENTRY be used instead. 


All ENTRY statements should appear immediately after the PACKAGE or RPACKAGE statement. Note: 
never put a USE statement before the ENTRY statements; if you do, you may get the ERROR message 
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ALREADY-USED-ELSEWHERE, meaning that the name of an entry is conflicting with an ENTRY in onc of the 
PACKAGES you USEd. ENTRY will also give an ERROR if it is used outside the body uf s PACKAGE. 


2.3.2. USE 

‘This function takes as arguments one or more STRINGs which are the names (as given to PACKAGE) of 
other PACKAGES. EXTERNAL is a synonym of USE. USE causes the entry OBLISTs of the PACKAGEs named 
to be spliced into the current OBLIST path. ‘Thus. references to entries of those PACKAGEs may be made 
afer the USE, until the next ENDPACKAGE (or the neat DROP or L-UNUSE if USE is being invoked outside a 
PACKAGE to load a file). 


USE is consequently the mechanism for sharing code. If the PACKAGE being used is already loaded, its 
entries sate made available; if not. the PACKAGE is loaded first (see section 4,1 for details un how this is 
accomplished). 


2.3.3. USE-DATUM 

USE-DATUM requires one STRING argument, the name of a data set, If the dita set is not loaded, 
USE-DATUM loads it and creates an ATOM of the same name, on the USE-DATUM OBL IST. whose GVAL is the 
data set. USE-DATUM always EVALS to the data set named, regardicss of whether it had to be loaded or not. 


2.3.4. DROP and L-UNUSE 
‘These functions take the same arguments as USE and USE-DATUM and undo their effects. 


DROP simply splices the named PACKAGEs out of the current OBLIST path. A USE of a DROPped 
PACKAGE will not reload the PACKAGE but simply splice it back into the OBLIST path. 


L-UNUSE splices the PACKAGE out and removes its name from the PACKAGE OBLIST, which will cause 
the entire PACKAGE to be reloaded if it is USEd again. L-UNUSE of a data set will remove its ATOM from the 
USE-DATUM OBLIST. 


2.3.5. ENDPACKAGE 

‘he ENDPACKAGE function of no arguments terminates the definition of the current PACKAGE and 
undoes the lexical blocking donc by the PACKAGE function. ‘The ENDPACKAGE statement should be the last 
‘one in the file. 
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2.3.6. PACKAGE Restrictions 
‘There are some restrictions on what the user may do inside a PACKAGE. ‘These are enforced by the I.ibrary 
System when the user attempts to submit a PACKAGE toa library. 


A PACKAGE should not FLOAD or LOAD any file to obtain parts of itself, All such environment setup 
should be done with USE and USE -DATUM, 


‘A PACKAGE may not reference any ATOM whose OBL IST path goes through the INITIAL OBLIST. All 
of'a PACKAGE’s non-cniry ATOMS should fall naturally into the PACKAGE’s internal OBLIST. 


As inentioned before, the RENTRYs of a PACKAGE have the same OBLIST status as SUBRS, i.c., they must 
be unique amwng both all SUBRs and «ll PACKAGE entries. 


2.3.7. ENTRY Name Conflicts 

Lis possible to have two or more PACKAGES (not RPACKAGEs) which have entries (not RENTRYs) with the 
same PNAME. If the user needs both PACKAGES at the same time, he may USE them both and refer to the 
ambiguous entries by their “full trailer’ names. All of the non-ambiguous entries in both PACKAGES may still 
be referenced by PNAMF only. 
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3. Program Writing and Debugging Aids 

This chapter concentrates on editing and debugging aids for MD programming. ‘The basis for editing and 
debugging in MDI. is twofold: Kirst, MDL isan interpreter, which permits interactive testing and debugging 
of software, Secondly, MDI. programs (even compiled Mbt programs) are structures and therefore may be 
munipulated by other MPI, programs. 


Packages useful in editing and debugging range from EDIT and PPRINT, which are preloaded, and which 
form the core of most editing or debugging systems, to more sophisticated aids such as DEBUGR and TRACE, 
‘which are more powerful, and useful for more complicated debugging. 


It should be noted that, in 


understand much of the syntax and many of the conventions of Mid! programs. 


dition wo the editors discussed below. RMODE [5] and EMacs [2]. THK 


3.1. Pretty-Printing 
The purpose of pretty printing 
human-readable format than that provided by the SUBRS PRINT, PRINA, ctc. Objects are pretly-printed 


to clarify the structure of MPi. objects by printing them in a more 


through the judicious insertion of spaces, tabs, and new-lines between tokens. Pretty-printed objects are 
readable by the Mbi Reader. Pretty printing is an aid to understanding and debugging MDI. FUNCT IONs or 
other objects, You will probably find pretty printing w be extremely helpful, especially if you are working 


without a listing or 


ith an old fisting. In fact, prety-printing is one way to make a new pretty listing after 
editing. PPRINT is pre-loaded in most initial MDs. ‘The name of the package containing PPRINT is "PP". 
<PPRINT gny channel> 

pretty-prints any on channel. The second argument is optivnal, by default .OUTCHAN , If any’ is an ATOM, 
PPRINT will enclose it in an application of DEFINE, DEFMAC, SETG, or SET, as scems appropriate. 
COMMENTS found inside any are right-justified. PPRINT cannot output an RSUBR without F IXUPs (that is, 
‘one that was READ in while KEEP-FIXUPS (see section 3.4) had no LVAL or had a FALSE LVAL); it will 
ive the ERROR message CAN-NOT-BE-DUMPED. PPRINT returns ,NULL, which is an ATOM whose PNAME 
isa single rubout, invisible on normal consoles. 


<PPRINF in:siring-uratourorlist outfile:siring 
width:fix. eval?:boolean> 


pretty-prints all the contents of in into ouyfile, 


If in is an ATOM or a LIST of ATOMS. its VALUE(s) are the objects to be PPRINTed. In this case, owyfle is 
by default a file whose first name is produced by taking the PNAME of in (or in's first clement, if in isa LIST). 
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If in is a STRING, if specifics a file containing objects to PPRINT. In this case, ouifile is by default 
*TPL:*, 


\widih is the maximum width of output lines (although ouput lines are prevented from being extremely 
Jong); itis optional, by default ¢13 ,QUTCHAN>. 


eval? tells PPRINF whether or not to EVAL everything in the file; it is optional, by default a FALSE (don't 
EVAL). eval? is meaningless if iis not a STRING, 


PPRINF returns cither “DONE” or a FALSE if it couldn't open injile or ouifile, PPRINF inserts page 
‘boundaries in owsfile, berween objects, every 60 lines or fewer; you may want to move these afterward ty more 
logical places. PPRINF binds KEEP-FIXUPS amd REDEFINE tw T, and QUICKPRINT (sce below) to a 
FALSE. 


3.1.1, PPRINT Control Switches 


PPRINT’s output is affocted by the locul values of several ATOMs. Each value is examined only for truth, 
-QUICKPRINT 


Ifthis ATOM’s LVAL is a FALSE, you are in slow mode: otherwise (Including the case of no LVAL), you are in 
fast mode, ‘The behavioral difference is this: in fast mode, there may be COMMENTS in the pretty-printed 
object(s) which PPRINT misses. Also, fist mode is indeed faster than slow mode, Fast mode is the default, 
that is, QUICKPRINT is initially truc. The modes are really distinguished by the depth of recursion to which 
PPRINT resorts. In slow mode. it recurses all the way down to every monad in the thing pretty-printed; in 


fast mode, it goes down only far enough to find something that will fit on a line, 
- LOOKAHEAD 


PPRINT uses full recursive lookahead to avoid packing things against the right margin and, as a result, not 
being able to fit things within the right margin. The lookahead results in very good formatting of 
deeply-nested MAPFed and FUNCT IONs: all but the most bivarre cases should be very legible. However, it 
can result in noticeable ‘pauses’ in the printing operation and, in some cases, a net spced slightly less than with 
lintited lookahead. Since this can be a disadvantage when using PPRINT interactively on a heavily-loaded 
system, the lookahead can be disabled: if the LVAL of LOOKAHEAD is a FALSE, no lookaltcad will be 
performed; otherwise it happens. LOOKAHEAD is initially truc, that is, lookahead happens by default. 
-VERTICAL 

If LOOKAHEAD is a FALSE. the formatting can cause too many objects to be squeezed against the right 
margin, So that particular cases can be made legible, the format when lookahead is not in use can be 
manually set: ifthe LVAL of VERTICAL is non-FALSE, PPRINT will indent very little whenever indenting is 


Pretty-Printing. 31 


The MDI. Programming Environment * ” 


called for. (VERTICAL being true means a “more vertical’ format.) VERTICAL is initially FALSE. The value 
of VERTICAL is ignored when LOOKAHEAD is truc; the lookahead effectively chooses different values for 
VERTICAL fur different parts of the object prety-printed, 


3.1.2. Lower-level Pretty Printing 
IL is sometimes desirable to use some of the fimnctions that PPRINT uses, but in a different way. For 

example, a specialized pretty-printer for Program Abstracts would want to insert indented field names into 
the output and pretty-print field values with the same indentation. ‘The names of lower-level pretty-print 
functions are included in the ROOT OBLTST for such purposes. 

<EPRINT guy lefi-margin:fix> 
prelty-prints avy on .OUTCHAN to the right of Jef-murgin. The second argument is optional, by default 
<VALUE LEFT-MARGIN> (sce below). 

<EPRIN any lefi-margin:fix> 
EPRIN1 isto EPRINT as PRIMI is to PRINT. 

-LEFT-MARGIN 
‘This is the ATOM that EPRINT binds to its second argument. You can SET it outside calls to EPRINT in order 
to make a permanent fefi margin. Its initial LVAL is 0. 

<INDENT-TO colwnn:fix channel 
‘outputs tabs and/or spaces to advance the output column (<14_ charnel>) to column, if itis not already past. 


<COLPP any 
channel 
lefiemargin:fix 
right margin:fix> 


preity-prints any on channel (by default .OUTCHAN) between the margins lefi-margin (by default 
<14 channel, the current column) and right-margin (by default <13 channel», the rightmost column), All 
‘arguments but the first. are optional.“ COLPP —rewms © NULL. For caample, 
<COLPP any .OUTCHAN 10 70> would leave a 10-character margin at left and right on an 80-column 
OUTCHAN. Also, 

<PROG () <PRINT AAAAAAAAAAAAAAA> <COLPP ,FOO>> 
‘would result in output like 


ANAARAAARAAAAAA #FUNCTION ((X GGGGGGGGGGGGGGGGGGGGGG) 
+x D) 


EPRINT, EPRIN1, and COLPP are affected by the truth of .QUICKPRINT, .LOOKAHEAD, and 
. VERTICAL. 
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3.1.3. Ampersand Printing 
“Ampersand printing’ consists of printing any object on a single line by using the character & (ampersand) 
to mean “There's more stuff here,’ (This technique is borrowed from the Inter isp editor.) 


There are two ways in which & is used by this printer as an abbreviation: 


1.An & appearing between sume varicty of brackets indicate "that there is a big object of the 
‘Indicated TYPE there, 


2.The charscters . .& oF &. . on the lef or right of a structure mean that there are more objects to 
the left or right which have not been printed. 


Examples: 
FUNCTION ((A BCD) <&>) 
‘This is a FUNCTION with four arguments in its argument LIST. and the FUNCTION body contains one FORM 


which was too big Wo print in the remainder of the line, 
<PROG () <KRK <+ .A 5>> <PRINC .Q> <SET BAR <ORG>> (&> &..> 


‘Vhis is a large FORM, namely, a PROG. In addition to the elements printed, there are more clemenis to the 
right, and there is one FORM which was too big to fit. 


Ampersand printing is effected by two pure RSUBRs: & analogous to PRINT, and &1, analogous to 
PRINA. A related RSUBR, &LTS. can be applied to no arguments to put you into an endless READ-EVAL-& 
loop, instead of the normal READ-EVAL-PRINT loop. 


3.1.4. Examining the Stack 

FRM fix> 
returns the fixth FRAME down from the top application of ERROR or LISTEN. 

FRAMES how-manycfix start:fix> 
pretty:prints how-many FRAMES (by printing the FRAME number (suitable as an argument to FRM), FUNCT, 
und ARGS of the FRAME), starting with <FRM star/>. Thoth arguments are optional; start defaults to 0, and 
how-many defaults to a large integer. A FRAME whose FUNCT is un ATOM whose VALUE is an FSUBR is not 
printed. if the same information is found in the next lower FRAME. 

<FR& howmany:fix start:fix> 
is like FRAMES but uscs ampersind printing instead of pretty printing. It is handy for summarizing FUNCTS 
‘and ARGS that are large or unprintable (like RSUBRS with no fixups). 
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<FRATM how-manyzfix start:fix> 
is like FRAMES but gives an abbreviated view of the stack. It prints FUNCT only, and only for FRAMES 
connected with named FUNCTIONS, RSUBRs, und RSUBR-ENTRYs, It is handy when a FRAME contains a 


non-LEGAL? object. 
<FRLVAL atom 

how-monysfix 

start:fix> 
Prints out the stacked bindings of atom. going through how many FRAMES, starting with FRM siart>. ‘The 
two numeric arguments are optional; how-many: defaults to a large integer, and start defaults to 0. ‘The 
format of the printing is two columns: the first column is the number of the FRAME in which «wom has a 
binding; the second column is the value bound, or a mnessage proctiiming the lack of a value. 


<FREVAL aiom 
howmany:fix 
sart:fix> 


\s precisely the same as FRLVAL, except that the values are ampersand printed instead of PRINTed. 


Finally, the "FRMSP” PACKAGE contains analogues of many of the preceding functions, but cach takes as 
its first argument a PROCESS, by default <ME>. ‘These are all named by adding a ‘P’ to the end of the usual 
name. For example, 

<FREP <MAIND> 
docs a <FR&> in the PROCESS MAIN. 


There is one additional function of interest in " FRMSP™. 

<ERTYPE how-manysfix. startsfix> 
is like FRAMES, but gives only the TYPEs of the arguments to cach. ‘This is useful in those situations when the 
stack shows illegal FRAMES or other unprintable objects. 


3.2. The MDL Editor 

EDIT allows a MDI. user to make incremental changes in Mp. structured objects, without leaving MDL. 
and with the ability to save the results in a file, and to set or clear conditional breakpoints of various sorts in 
‘objects that will be evaluated, stich ss FUNCT TONS, 


EDIT is an cditor/debugger written in, written for, and running under MDI. It comprises the package 
“EDIT™ and several smaller packages which will be mentioned later in this section. EDIT is preloaded in 
‘most initial MDL. 


‘To start editing, apply EDIT to no arguments or to the name of the object you wish to edit: <EDIT> 
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causes entry into EDIT and opens the last object edited; EDIT objeci> causes cntry into EDIT and opens 
object for editing. Permissible objects include: 


— ATOMs. ‘The GVAL (preferably) or the LVAL of the ATOM is opened. If it hus no value, EDIT 
returns a FALSE. 


— APRIMTYPE LIST. ‘The PRIMTYPE LIST is opened, 


— AFIX. The stack frame with that number is opened (i.e,, CARGS <FRM fix>>). 


Part of EDIT’s efficiency comes from forbidding it to delve into objects that are not of PRIMTYPE LIST, 
that is, not LISTS, FORMs, FUNCT IONs, ctc. Attempts to edit objects of uther PRIMTYPES will result in error 
messages. ‘Ihese objects can, however, be treated as units when inserting, searching, etc.: oF they can be 
changed into LISTs, edited, and then changed bock to their original types. 


3.2.1. The Edit ‘LISTEN Loop’ 


3.2.1.1. The Reader 
When in EDET. you are typing at a special, non-standard, input function: ‘The EDIT Reader. 


“The Reader allows you to type EDIT commands and have them executed, and also to evaluate MDL 
expressions normally. Its characteristics are as follows: 


— Asin the normal MDL Reader, nothing is done until you type ESC. DEL, tL, *D, +6, and +5 also 
work normally. 


— All EDIT commands are terminated when an ESC is encountered in the input stream. In 
addition, most commands will terminate whenever the maximum number of arguments required 
has been input or whenever an argument of the wrong type is encountered. In the former case the 
next object is taken as a new command: in the latter case the object of the wrung type is taken as a 
new command, EDIT commands may be typed in either upper or lower case, 


— If you type something that EDIT docs not recognize as a command, normal MDI. evaluation and 
printing are performed on that something. This evaluation will have no effect on your position in 
the object you are editing. 


— While editing a function which is part of a PACKAGE (determined from an examination of the 
OBL IST containing the ATOM whose value is the function), EDIT causes the OBL IST path to be 
set up to what it was in the environment of that PACKAGE. ‘This has the advantage of reducing the 
number of trailers printed, and causes newly entsred ATOMS to fall on the correct OBLIST (the 
internal OBLIST of the PACKAGE). It has the slight disadvantage that it disables the dynamic 
loader (which depends on unbound variables falling on the INITIAL OBLIST). Ifthe GVAL of 
E-PKG is a FALSE, this feature is disabled, and the normal OBLIST path is in effect during 
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sits 
Examples: 
R 6S 


Causes exccution of EDIT command R, with argument $. 
AR OS 


Causes application of the function R to S. 


3.2.1.2. The Ampersand Printer 
‘Your current position is displayed by ‘ampersand printing® (sce section 3.1.3). ‘This consists of printing any 
‘object on a single line by using the character & (ampersand) to mean "There's more stuff here.” 


‘The ampersand printer used in E017 is much like the standard one, with the addition that your current 
ponition (see below) is displayed by the glyph 


‘When you initially enter EDIT. you are in a mode called "non-\erbese,” in which ampersind printing is not 
automatically done following execution of EDIT commands, ‘The V command is used to toggle you in and out 
of verbose mode (see below). 


Examples: 

#FUNCTION ( B (AB CD) <&>> 
Indicates that your position is just to the left of a FUNCTION’s argument list, and the FUNCTION body 
‘contains one FORM which was too big to print. 

<..8 CKRK GA 62> © CSET BAR <ORG>? <&> &..> 
Indicates that you are in the middle of a large FORM (c.g., a REPEAT or a PROG), positioned just to the left of 
the <SET BAR <ORG>>. In addition to the objects printed, there are more objects to both the left and the 
right, and there is one FORM which was too large to fit on the tine. 


3.2.2. Edit Commands 


3.2.2.1. General 

‘A sequence of EDIT commands is executed as soon as you type ESC. Ifone command fails, subsequent 
commands up to the ESC are ignored, and EDIT types out an appropriate crror message. A failing E01T 
command generally has no effect whatsoever; but sec individual descriptions. 


Note that al! arguments to ED1T functions must be legal Mp1 objects. In partkular, you can't search for 
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<SET . since the <>'s aren’t balanced. Nor can you insert it. (But you can, fur instance, search for and insert 
<SET THING 1>.) 


Ifa command expects an argument and doesn't get one, an error message will be printed, 


Many EDIT commands take F1Xes as arguments. ‘Those that do interpret the ATOM ® as an argument to 
mean ‘as many as possible’. 


Whenever you are in EDIT, you have a well-defined ‘position’. A position is a ‘place’ inside a MDI. 
structure: this ‘place" is either berween two clements of the structure, oF berween an clement and cither end of 
the structure, or inside an empty structure. All editing, movement, and printing commands operate relative to 
your current position. ‘The term ‘cursor’ is used in the following descriptions to refer to an embodiment of a 
position. 

‘The format used in cach of the following command descriptions is: 

Command as Typed English Name 
Description 
3.2.2.2. General Commands 


? dun? 


Causes a short summary of all EDIT commands to be typed out. The same summary appears later in this 
chapter. 


ad huh? 
‘Similar to the above, but the summary is even shorter, and should fit entirely on the screcn of an Imlac 
terminal. 


Q Quit 
Leave EDIT and return to MP1. (Causes EDIT to return the ATOM T.) 


QR fix Quit and Retry 


Quit from EDIT and then retry the frame specified, or by default, the one originally given to an open 
command or, if none was given, the frame beneath the last ERROR or LISTEN frame, 


vr Control-F 


“This is not really an EDIT command: rather, itis @ character, obtained from the input stream at interrupt 
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level, which is used to return you to the EDIT Reader from some higher level of application, ¢.g..an ERROR'S 
LISTEN, Itis the EOTT equivalent of ERRET with noarguments. 


1F (or +S) typed during execution of an EDIT command is similar to normal MDL +S but returns to the 
EDIT Reader instead of the Mid. LISTEN loop. 
0 wbicct Open 


Fquivatent to Q followed by <EDIT object>. Positions the cursor just to the left of the first clement of the 
entire object specified. 


or Open This 


If the object to the right of the cursor is an ATOM, or a FORM whose first element is an ATOM, and the 
AVOM's value is openable. then Its opened. ‘This command is useful when tracing a calling sequence through 
several functions, 
3.2.2.3. Movement Commands 


ur Up to the Top 
Places the curse: at the position # had following an 0, 


R fix Right 


Moves the cursor fix objects to the right, by default one. If fix is wo large, ic. there are not that many 
positions to the right of the current position, EDIT prints an error cominent and the cursor stays where itis. 


8 Back 
Moves the cursor as far to the right as possible. 


L fix tert 


Moves the cursor fix positions to the Ie, by default one. If fix is too large, EDIT prints an error message. 


Front 


Moves the cursor as far to the left as possible, 


OL Down Left 


Positions thee cursor just to the right uf the rightmost ciement within the object to the left of the cursor, if 
that object is of PRIMTYPE LIST. Visually, the cursor moves left over one “clase bracket" 
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oR Down Right 


Positions the cursor just w the left of the leftmost element within the object to the right of the cursor, if 
that object is of PRIMTYPE LIST. Visually, the cursor moves right over onc ‘open bracket’. If the cursor is 
to the Ieft of an clement that is not of PRIMTYPE LIST. EDIT prints an error message. 


o Down 
Equivalent to DR. 
UR fix Up Right 


Positions the cursor just to the right uf the object the cursor is currently within, Dues so fix times, by 
default once, 
UL fix Up Left 


Positions the cursor just to the lefi of the object the cursor is currently within. [Does so fix times, by default 
once. 


U fix Up 
Identical wo UL. 
S object Search 


Does a depth-first, lef-firsttree-walk, (ie., le-to-right) starting with the object to the right of the cursor, 
until the cursor is just to the right of an object structurally equal (ic., =?) to its argument. An occurrence of 
the object will not be found if it is inside anything not of PRIMTYPE LIST. On failure, the cursor docs not 
move. [Fthe argument is omittsu, the last object scarched for is used. 


SR object Search Right 
Same as S. 
‘SL object Search Left 


Same as S, but the tree-walk is depth-first, right-frst (ic. right-to-Ief) and you end up w the lef of the 
object for which you were searching. 


3.2.2.4. Printing Commands 
The Empty Command 
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‘Cautses the normal ‘ampersand print’ tu be done. “This is principally usefial when you are in ‘silent’ mode; 
see the V command. 


Hy the way, an ‘empty’ command is typed by typing ESC without having typed any visible characters 
before it. 


Pp Print 


PPRINTS (not ‘ampersand prints) the object to the right of the cursor. 

Pu Print Up 
PPRINTS the object the cursor is in, ‘This is similar to doing a U and then a P. although the cursor is not 

moved. 

1 Print Top 
PPRINTs the whole object you have open. 

v Verbosity 
“Toggles the verbosity mode between “verbose” (most commands cause ampersind printing) and ‘silent’ 


(printing of any sort is done only when some explicit print command is used, or when an error occurs). The 
current state of verbosity is the GVAL of E-VERBOSE, 


In silent mode, absolutely nothing is printed after cach command, not even new-lines or prompts. 
However, normal MDL evaluation still causes normal MDL printing. 
3.2.2.5. Editing Commands 
1 gy -.. Insert 


Inserts al ts arguments immediately to the right of the cursor. None of its arguments are evaluated; you 
can insert unevaluated FORMS without using QUOTE. ‘The cursor ends up to the right of the last object 
inserted. 


G amy... Get 


‘Same as 1, but its arguments are evaluated. ‘This is useful in conjunction with the X command (see below). 


1s pypecatom fix Insert Type 


Grabs fix objcets to the right of the cursor, inserts them into a newly created object of TYPE type, deletes 
them from the original structure, and inseris the newly created object in their place. In other words, it “inserts” 
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the appropriate open and close brackets for /ype at the cursor and fix objects to the right. 


Ry default fix is one, type is LIST. An error message is printed if fix is larger than the number of objects 
tw the right of the cursor. 


There is no way to directly insert or delete single parentheses, brackets, etc, using EDIT, Instead. use Kz 
(see below) to remove pairs of brackets, and 1: to insert them. 


1° indicatorsatom ew-siructure Imbed 


Imbed looks for all occurrences of indicator in new-siructure and replaces these occurrences with objects 
taken and deleted from the right of the cursor. It then inserts the result. 


[Fonly nen-structure is given, the indicator is the ATOM *. If there aren't cnough objects to the right of the 
cursor to replace each indicator, remaining indicators are le untouched and a warning inessage is printed, If 
‘ho indicators are found, the new structure is inserted, but a warning message is printed, 


T+ is generally used to insert one or more structures into another complex structure in one operation, 
instead of several. For example: 


<SET X B12 .¥>> 
T* <COND (<NOT LENGTH? .Y 11>> *)>$ 
SET X <COND (<NOT <LENGTH? .Y 11>> <12 .¥>)> > 


places a protective conditional around an NTH to prevent an out-of-bounds error. 

16 amvu Insert into Group 
Inserts into a group. 1G is similar to I, but assumes that the object you are in is a group (as produced by 

GROUP-LOAD). Arguments to 1G which are not ATOMS are inserted as in I. Objects which are ATOMS and 

which have a value insert a FORM which DEFINES, SETGs, or SETs the ATOM as appropriatc. ‘Thus, to add a 


‘new function F to a group G, one could type 
0 GSIG FSos 


K fix ki 


Neletes fix objects to the right of the cursor. Defaults to une. Negative fix causes deletion to the left of the 
cursor. 


C ow Change 


Changes the one object to the right of the cursor to its single argument. Docs not move the cursor. Docs 
not evaluate its argument. C is more efficient than K plus I, 
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C: ppecatom Change Type 


Changes the type of object to the right of-the cursor to ‘ype. Attempts to do something reasonable for 
every type change. If you tell it to change a STRING to a LIST. you gct a LIST of CHARACTERS. If you 
attempt to change a structure whose clements are other than CHARACTERs and STRINGs to a STRING, you 
will gota MDL. error. 


Kill Type 

Neletes the brackets around the object to the right of the cursor. Lc. kills the object and inserts its 

clements into the structure of which it was a par. 

‘SU new old Substitute 
‘The Substitute command takes two arguments, All accurrences of old from the current location t« the end 

uf the open abject (actually a scarch-right is dune) are replaced by new. Once the search for uld fails, the 


command terminates, and the number of substitutions performed is printed, ‘The cursor is lef after the last 
object replaced, 


* atom Transfer 
SET» the atom to the object to the right of the cursor. X can be used with K and G w move things around 

within the object being edited. 

sw Swap 
Swaps the two objects to right of the cursor, leaving the cursor pointing at the same object. The effect is to 


move the cursor and the object it points at one object to the right. Repeated SWs move cursor and object, 
further and further to the right. 


3.2.2.6. Macro Facility 


™ macro Macro 


Fakes cither a STRING or something which EVALs to a STRING and performs all of the commands in the 
SIRING. For complete assurance that your commands will be done properly, put an ESC between 
commands, 


11 fix macre Iterate 


This command (also called DO) takes a fix and macro as if an argument to M. This command will loop 
through the macro fix times or until an error is generated. When the iteration ends, the user is told how many 
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complete passes have been made of the macro, 


In both of the above commands, if an ED1T error is generated, the macro will be terminated, and the 
‘macro itself will be printed, with an arrow pointing to the offending command. The cursor will remain at the 
place where the last legal command left it. 


“The SU command is, internally: 
DO * "S olfSLSC news* 


3.2.2.7. Cursors. 

Cursors are locations in objects being EDI Ted. In addition to the main cursor, which is where editing 
occurs, ather Iecations (also called cursors) may be remembered, ‘The main cursor may be moved to another 
cursor in a single wperation, potentially saving many motion commands. In large FUNCTIONS cursors may 
also reduce confusion by distinguishing among several similar arcas of code, 


ue Use Cursors 
“he PACKAGE for dealing with cursors is not normally loaded in an initial Mbt. so the UC command loads 

itand makes the cursor commands available. ‘The PACKAGE loaded is “CURSOR”. 

CU atom Cursor 
CU tikes an ATOM argument and SEs the ATOM tu an object of type CURSOR, which tries to be clever in 


the event you change the object. Also. if you use the X command to name a substructure and then move copy 
it with G or f, the cursors in the substructure will follow to the new location. 


‘There are some restrictions. Cursors in empty LISTS are okay but they will not follow the object to new 
locations. Also this ‘following’ feature is effective unly at the first G or T after the X. ‘To move the substructure 
again you have to X again. 

T* is somewhat incompatible with CURSORS. Cursors in Imbedded structures will sometimes disappear, 
GO cursor Go 

GO takes a cursor (normally the LVAL of an ATOM previously given as an argument to CU) and GOes to that 


position. If the eursor is illegal (not in the current top-level structure). an error message will be printed and 
you will remain in your previous position. 


KC atom Kill Cursor 
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Kill the cursor assigned to atom. 


Pc Print Cursors 


Prints all cursors in the structure to the right of the main cursor. 


PA Print All Cursors 
Prints all cursors in the currently open structure. 


3.2.2.8. Br 


kpoints 


BK predicate any ... Breakpoint 


Inserts 9 breakpoint ‘around’ the object to the right of the cursor, ‘Takes any number of arguments. 


Subsequently, whenever that object would have been evaluated. you instead hit a breakpoint function which: 


Evaluates predicate. If the value is FALSE, evaluation continues as if there were no breakpoint, If 
the value is non-FALSE. or if BK was given no arguments: 


2. Types **BREAK**. 


3. For each argument afier the first that you gave BK, types 
arg = EVAL of arg 


4, Enters LISTEN. 


You continue by applying ERRET to one argument, just as from an ERROR; the argument's value is ignored. 


Breakpoints are implemented by inserting a BREAKR (a PRIMTYPE LIST with APPLYTYPE FORM) 
which consists of the function BREAKR and arguments, including the object breakpointed. A breakpoint 
prints asa glyph similar to the cursor: 

Hobject 
Ifthe ATOM SHORT-PRINT is assigned and FALSE, the actual BREAKR LIST is printed. 


‘The breakpoint function returns EVAL of the thing it is put ‘around,’ and there are cases where this does 


nut work. ‘There are always equivalent places that do work. 


1. Breakpoint on the first clement of a FORM docs not work. Put iton the whole FORM. 


2. Breakpoint on a LIST which is an argument to a COND docs not work. Put it on the first FORM in 
the LIST. 


BA predicate any... Break After 
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Similar to BK. but puts the breakpoint affer the object at the cursor. Its action is like that of BK except that 
the browk occurs after the object it is on is EVALed, 


This sort of breakpoint prints like the "before sort, but with the glyph after the object broken: 

object 
The predicate for a BA breakpoint may check the value returned by RYAL for the abject the breakpoint is on, 
‘This value is assigned by BREAKR to the ATOM VALUE. 


KT M401 This 


Removes the breakpoint (if any) from the object to the right of the cursor. 
KB Kill Breakpoints 


Removes all breakpoints in the currently open object. 


3.2.2.9. Edit Monitors 
There are several commands in EO1T which provide a simple interface ww the “MONITOR™ PACKAGE. 
‘These allow placing of monitors un references to or modifications of LVALs in interpreted MDI. code. 


For a more complete discussion of the use of monitors, see secuon 3.7. 


uM Use Monitors 


The PACKAGES for dealing with monitors are not normally loaded in an initial MDL, so the UM command 
toads them and makes the three commands for creating monitors available. “The PACKAGES loaded are 
*MONITR™, which is the gencral monitor PACKAGE, and "EMONIT™, which is the interface between EDIT 
and "MONTTR®. 


RW atom predicate any ... Read-write Monitor 


‘The most general type of monitor that can be set is a read-write monitor. It will catch any reference to or 
‘attempt to modify the LVAL of the aom specified. The restrictions on placement of breakpoints also apply to 
monitors, with the addition that a monitor on an LVAL must be pliced after that LVAL has become 
ASSIGNEO?. 


“The sccond. third (and so on) arguments to RW are the same as those for BK. The predicate may be 
dependent on either the new or old value of the variable: ‘Ihese are avaitable as the LVALs of NEWVAL and 
OLOVAL, respectively. 


‘The MDL Editor 32 


The MIL. Programming Environment 31 


When a monitor is triggered, it prints the type of monitor, the variable being monitored, and any other 
information requested by the user, and then calls LISTEN. 


‘A monitor prints as yet another glyph: 
NLaiom]object 
where atom is the ATOM being monitored, and object is the object on which the call to MONITOR is placed. 


Edit monitors are objects of type BREAKR, and thus they arc killed by the same commands that kill normal 
breakpoints: KB, KT, and so on. 


RM alom predicate ‘any Read Monitor 


RM is analogous to RW, but is only triggered by reading the variable. 
WM giom predicate any ... Write Monitor 


WM is analogous to RW, but is only triggered by writing the variable. 


3.2.2.10. User-defined Edit Commands 

It is possible to add user-defined commands to EDIT. ‘The value of EDIT-TABLE should be a VECTOR of 
STRINGs (commands) and APPLICABLE objects. EDIT will scarch EDIT-TABLE before its own command 
table, Ifa match is found, the APPLICABLE will be applied to three arguments: the command string, the 
LOCATIVE containing the item currently being edited (the immediately surrounding object) and the position 
in that item. 


Note that user-defined commands should not be added except by constructing a new value of 
EDIT-TABLE from the commands to be added and the old value. Otherwise, any cxisting user-defined 
commands may be lost when new ones are added, 


‘The Monitor commands described in section 3.2.2.9 are effectively ‘installed’ user-defined commands. 
hey add elements to EDIT-TABLE when loaded by the UM command. 


3.2.3. Examples 


3.2.3.1, Simple Editing 
‘Suppose you have the FUNCTION 
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MFUNCTION (('A) EVAL .A>) 


1s the global value of the ATOM STMP. and you wish (o change it to 
MPUNCTION ((“BIND" B 'A) (EVAL .A > .A)) 
jasing EDL. ‘The follawing example does Just that: it includes doing the editing and applying of STMP to an 


argument. Console input and output are shown below exactly as they would be in non-silent mode, (Console 
\nput consists of thase characters to the left of every $). Note that there is nothing in SIMP which Is big 


enough to warrant use of an &. 
<EOIT SIMPDS 
vs 


WFUNCTION ( § (A) 
os 

{ 
1 

(*8INO" BOR ‘AD 


S .AS 
EVAL .A BD 


EVAL .A 8 9D 
URS 

#FUNCTION (("BIND™ 
I .AS 


#FUNCTION (("BINDY 
L2s 


FUNCTION ( (“BIND” 
I: LIST 25 
ATUNCTION (("BINO" 
<SIMP C+ 1 2098 
{3 < 12>) 
FUNCTION (("BIND* 
sr 


EVAL .A>) 


‘A) SEVAL .A .B> @ ) 
‘A) SEVAL .A .B> .A BD) 
*A) § SEVAL .A .B> .A) 


*A) B (EVAL .A .8> .A)) 


*A) HW (SEVAL .A .B> .A)) 


3.2.3.2. X and G Commands 
{In this cxamiple we have the FUNCTION 


COEFINE F (X) 
<G .X 10> 


cH 23 <- .k DDoS 
Ay applying the X and G commands to the appropriate FORMS, we are able to swap the FORMs within the 


FUNCTION, 
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<DEFINE F(X) 
<G .X 102 
<H 23 <x 19208 
' 
<EDIT F>$ 
$ 
FUNCTION ( B (XK) <G .X 10> CH 23 <- .x 19>) 
RSS 
#FUNCTION ((X) BCG .x 10> <H 23 <- 1x IS>) 
X MOVERS 
WFUNCTION ((X) B <G .x 10) <H 23 <- 2X 199) 
KSS 
WFUNCTION ((X) B <H 23 <= .Xx 19>) 
RSS 
FUNCTION ((X) <H 23 <- .% 19> B) 
G .MOVERSS 
FUNCTION ((X) <H 23 <= .K 193 <G LX 10> B } 
gst 
-MOVERS 
<G .X 10> 


3.2.3.3. Unconditional Breakpoints 
Ta insert unconditional breakpoints into the FUNCT ION in the next example, do the following: 


1. Define F18 and test the FUNCTION a few times. 
2. Enter ED1T and position the cursor appropriately. 
3. Insert the breakpoint. 


4.1.eave EDIT and run the FUNCTION again for the value 3, The breakpoint is exercised 5 times 
uring this run. 
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OEFINE FIB (x) 
<COND (<L=? x L> .&) 
(ELSE <+ <FIB <- .& 2>> CFIB C- .k DIS 
Fie 
<FIB 6S 


5 

<FIB 8>S 

8 

<FIB 10>$ 
55 

EDIT FIBDS 


WFUNCTION ((X) B <&>) 

Bk T .xSQST 

<FIB 39S 

**BREAK*® 

23 

LISTENING-AT-LEVEL 2 PROCESS 1 
CERRET TS. 

**BREAKS* 

kad 

LISTENING-AT-LEVEL 2 PROCESS 1 
ERRET TDS 

**BREAKS® 

k=2 

LISTENING-AT-LEVEL 2 PROCESS 1 
<ERRET TS 

**BREAKS® 

k= 0 

LISTENING-AT-LEVEL 2 PROCESS 1 
SERRET T>$ 


LISTENING-AT-LEVEL 2 PROCESS 1 
<ERRET TS, 
2 


3.2.3.4. Conditional Breakpoints 
‘We continue from the previous example and demonstrate conditional breakpoints with the following: 


1. Enter EDIT and kill the breakpoint from the previous example. 
2. Position the cursor and insert a conditional breakpoint with a predicate of <0? .X>. 
3. Leave EDIT and run the FUNCT ION again for the value 10. 


4. Enter EDIT and remove the breakpoint. 
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<E0IDS 

s 

FUNCTION ((X) © §<&>) 

Kass 

#FUNCTION ((X) & <&>) 

BK <0? .X> <TIMEDSOST 

<FIB 1038 

BREAK** 

<TIMED = 14.794538 
LISTENING-AT-LEVEL 2 PROCESS 1 
XS 

0 

<ERRET TDS 

**BREAK** 

<TIMED = 15.252362 
LISTENING-AT-LEVEL 2 PROCESS 1 
xs 

0 

<ERRET TS 

*BREAKS* 

<TIMED = 15.716037 
LISTENING-AT-LEVEL 2 PROCESS 1 


‘and so on, Eventually we reach the last breakpoint, and re-enter EDIT 
<EDITS 
$ 
WFUNCTION ((X) B §<&>) 
KBSQST 
<ERRET TS 
55 
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3.2.4, Edit Command Summary 


Movement 

t 

R fix 

u fx 

o none 
8 mone 
F mone 
UR fix 
oL fx 
ur none 
Editing commands 
T baad 
r wpe fix 
I atom,object 
IG aNynn. 
su 

x atom 
6 Aye 
si none 
c any 
c: pe 

K Sx 
kK: none 
Scarch Commands 
3/SR amy 
st am 
Macro Commands 
The MDL Editor 


MEANING 


type out short summary 

type out this summary 

Open object or the value of an atom 
‘Open object at the cursor 

Quit and return to MDL 

Quit and Retry frame 

toggle Verbosity 


move Left fix objects 

move Right fir objects 

mone Up fix levels 

moe Dawn one level 

moxe to Rack of abject 

more to Front of abject 

nove Up fix objects and to the Right 

move Down fix objects and to the Left 

Up Top ~ go to the place you were after you did 0 


Insert arguments to the right of cursor 

make next 1 objects into a type 

Imbed command: replace all occurrences of atom (default *) 
in object with objects to right of cursor 

Insert into group 


SUbstitute new for old 

set the atom to the object to right of cursor: 

Get EVAL of arguments, insert to right of cursor 
3Wap the two objects to the right of cursor 
Change the next object to arg, 

‘Change the type of the next object to (ype 

Kill (delete) the neat fix objects: 

Kill (remove) the "brackets' around the next object 


Search (Right) until match (=?) is found for any 
Search Left as above 


ment 


The MDL. Programming Environment ° 


” suring 
11/00 _fix.string 
Printing commands 

P none 

PU none 

PT none 
Cursor commands 

uc none 

cu aon 

Go cursor 
Pc none 

PA none 

Kc atom 
Debugeing commands 
BK predany... 
BA Pred.any... 
kB none 

xT none 


‘exccute the string as if typed to EDIT 
MTerate the exceute string fix times 


PPRINT the next object 
PPRINT the next Upper level 
PPRINT the whole object open 


Use Cursors 

set alom to CUrrent cursor position 

GO w the specified cursor position 

Print Cursor positions in the current object 
Print All cursor positions in the top-level object 
the Cursor assigned to the atom 


set BreaK point at next object: if pred evaluates to FALSE, 
don’t break: rest of arguments are printed out at break 
set Breakpoint After next object 

Kill all Breakpointsin open object 

Kill ‘This breakpoint in the object to the right of cursor 


‘Use Monitors 

‘set Read-Write monitor on atom 
set Read Monitor on atom 

set Write Monitor on afom 


‘tF and tS return you to EDIT from a higher level. 


“The ATOM * may be used as a fix argument whose valuc is the largest legal value for that command. 


3.3. Debugging and the Interpreter 

Before cuntinuing the discussion of the various packages that are used in the debugging of Mb. code, we 
will expand on the discussion af ERROR, F RAME, (and so on) in Chapter 16 of (3). ‘To summarize that chapter, 
whenever an ATOM is bound or a FUNCTION or RSUBR is MCALLed in MDL, information is added to the 
contol stack. ‘This information, normally ‘invisible’, may be examined using the functions described in @ 
previous section (FRAMES, FR&, FRLVAL, ctc.). ‘An invocation of ERROR puts MDL into a LISTEN-like loop. 


32 


i] 


‘The MDL Editor 


8 The MIDI. Programming Environment 


Successive ERRORS stack up and are reflected in the LISTENING-AT-LEVEL message printed whenever 
ERROR or LISTEN is called. 


In addition to being examined, the stack may be modified as part of the debugging procedure, For 
zxample, the SUBRs SET and LVAL take an optional sccond argument which may de (among several possible 
TYPES) a FRAME. EVALing 

<SET X 10 <FRM m> 
would change the LVAL of X in the nearest binding lower in the stack than the FRAME n FRAMES lower than 
the most recent cull to ERROR of LISTEN, Similarly 

<LVAL XK CFRM n> 
examines the LVAL in a particular FRAME, 


“The most comnmwn use of the Mit. interpreter in debugging is to invoke the SUBR ERRET. With no 
arguments, it drops all the way tw the bottom of the stack and then calls LISTEN: It says"I give wp” (although 
side effects are not undone). More cummonly, ERRET is given a single argument, which causes the last 
invocation of ERROR vr LISTEN to return that argument. For cample. suppose a program contains , FOO 
but FOO has no GVAL. Mb. would respond 


*ERROR® 
UNASS IGNED-VARTABLE 
Foo 


‘GVAL 

LISTENING-AT-LEVEL 2 PROCESS 1 
You could give up, saying CERRET>. but it is uften more reasonable to say “Oh, yes. FOO was supposed to be 
1000", and then 

<ERRET 10009 
‘Still better Is 

CERRET <SETG FOO 1000>> 


which will prevent future ERRORS from the same cause. 


Finally, ERRET may be given a second argument ofa FRAME, which means to return the First argument as 
the value of the invocation of that FRAME. In the previous example, the programmer might look at the stack 
(with FR& oF FRAMES) and see 
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1 GVAL 

2 EVAL 

3 EVAL 

4 EVAL [<LOSER .A .6>] 

6 EVAL [</ ,GOOD-GVAL <LOSER .A .8>>] 
6 EVAL [<WINNER 1.0 2.03] 

7 LISTEN fal 


‘Afier some thought, he may just suy “Well, LOSER apparently needs some debugging, but for now I'm 
interested in WINNER’. in which case he can ‘fake’ a reasonable return from LOSER by typing 
<ERRET 342.0 <FRM 43> 
which rewimns 342.0 exactly as though LOSER had returned it. 


More complex errors are sometimes more difficult to fix, requiring tie use of EDIT (atleast), In the above 
sample, the programmer might decide to debug LOSER after all. ‘There are two ways to go about this: First, 
‘the problem is localized, the FRAME itself may be edited (which is to say. the contents of the FRAME may be 
ccdited), Changes will show up in the FUNCTION from which the FRAME's contents were derived. ‘The newiy 


corrected FRAME may then be RETRYed. Hor example, 

<EDIT 38 

sw tarious editing commands 

QRS 

Second, the function itself may be edited. In the process. it may be so changed that the FORM which 

caused the ERROR no longer even exists. Often, the easiest solution is wo reiry the invocation of the ED1Ted 
JUNCTION from scratch: in this case 

<RETRY <FRM ADDS 


As always, the major restriction to remember is that side-effects are not undone by RETRY. 


3.4. Loading and Dumping 

GROUP-LOAD and GROUP-DUMP arc used \ load and dump files of MDI. programs in such a way that the 
contents of the file are made available in a MiDi structure called a group, Many other PACKAGEs in ure MDL 
environment operate on or change groups: Among them are "EDIT". "GLUE", *PDUMP™, and the MDL 
compiler, 


GROUP-LOAD and GROUP-DUMP are almost as widely used as FLOAD 2s # way of dealing with groups of 
Mont. functions. Conscquenily, they are alrcady loaded in most initial MDLS, as part of the package 
“GRLOAD* 
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GROUP-LOAD firname:sieing 
group-namesatom> 


{leenamte:siring is Une Filet load. 


sroup-namecatom is the name to give the group. Jk Is uptional and by defiult the ATOM formed by PARSE of 
the first nome of the file to load. "The group will be stored as the LVAL of group-name. 


3ROUP-DUMP Is the opposite of GROUP=LOAD. It outputs the group frum the Mb. whe file given as its 
first wrgument. Functions unchanged since the last GROUP-LOAD are copied from the original input file. 
Hunctions that have been edited are output using the routine given as the third argument to GROUP -DUMP, 
(GROUP-DUMP fle-name-sring 


‘graup-munezatorn 
print-routine 
Aill-breakpomts?> 


iHe-numessteing is the only required argument. Its the file w which w output the group. 


group-namecatom is optional, nd defaults as it does for GROUP-LOAD. but of course gives an ERROR if the 
soup doesn’t already exist, 


ortht-routine soptional, and defaults ws , PPRINT unless the group contained NOIN format RSUBRs, in which 
case , PRINC Is used. 


SUlb-breakpoints? is optional, by default T. in which case GROUP-DUMP kills all EDIT breakpoints and 
monitors in objects being dumped. Giving a fourth argument of a FALSE tw GROUP-DUMP prevents this. 


On the surface, it appears that litthe happens in the process of foading a file and making it into a group. 
However, a great dea of information about the group has becn stored away in associations for later use. 
Some of this information is of use to the Mit. programmer: 


|.On an association between group-namme and the ATOM CHANNEL is stored a LIST giving the name 
uf the file that was GROUP-LOADed to form the group. Removing this association before 
GROUP-DUMPing has the cffect of making the entire group be output from cure rather than 
cupied from the original source, 


2,On an association between group-name and the ATOM MAGIC-RSUBR the ATOM T is stored if the 
group contained any RSUBRs in fast (NBIN) format. It is this association which is used to 
Uetermine the default prit-rowtine in GROUP -DUMP. 


3.'The OBLIST path in effect at any time during the load is available. ‘The original path is swured on 
an association between graup-neme and the ATOM BLOCK. SWithin the group, the path changes are 
stored in an association between the group RESTed to the point of change and the ATOM BLOCK. 


4. If the second clement of a FUNCTION definition is not an ATOM, the actual FUNCTION name 
gotten by EVAL of that clement is stored as an association betwen the original element and the 
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‘ATOM VALUE. 


§. The location of a function within the input file is stored as a LIST of the starting and ending 
offsets (in characters) of the function, under an association between a locative w the GVAL of the 
FUNCTION name and the indicator DEFINE. ‘This association is removed by EDIT (and other 
editors) to indicate drat the FUNCTION has been changed. 


‘There are additionally several switches that affect the operation of GROUP-LOAD; 
.KEEP-FIXUPS: 


IU the LVAL of KEEP-FIXUPS js truc (und GROUP-LOAD binds it that way during loading). the fixups of 
NSUBRs GROUP-LOADed will be kept. 

-EXPFLOAD 
IUthe LVAL of EXPELOAD is truc, FLOADs will be expanded. ‘That is. the objects in the file FLOADed will be 


ulded to the group in place of the FLOAD. ‘The initial setting of EXPFLOAD is a FALSE. 
-EXPSPLICE 


WW the LVAL of EXPSPLICE js truc, any objects reused within SPLICEs will be inserted directly into the 
jnoup as described above. ‘The initial scuing of EXPSPLICE isa FALSL, 


3.5. The One-step Debugger 

The Mbt. One-step debugger allows the user to step through the evaluation of any MDI expression one 
operation’ at a time. Between steps, variables may be examined or changed. functions edited, and so on. 
‘This is possible because the debugger runs in a different MDI. PROCESS than the expression being stepped, 
anda MDE PROCESS may 1STEP another 3}. To load the Debugger. <USE “DEBUGR™>. 


The Mist. Debugger can be in any of three states. In the initial state, OF F. no one-stepping occurs and the 
Debugger does not listen for any special interrupt characters. The Debugger is, therefore. completely inactive, 
Wy typing <DEBUG> to MPI. you leave the OFF state and enter the READY stale. In the READY state no 
one:stepping occurs, however the Hebugger docs listen for interrupt charscters. By typing the interrupt 
lhyracter 1B, you enter the ON state and one-stepping begins. In addition, if you were stopped at an EDIT 
ivakpoint When the 1B was typed, the breakpoint will automatically be exited and evaluation continued in 
the nnestepping state. 


While in the ON state, the Debugger will proceed through the execution of any MDI. objects one step at 
vie Invessenge, the Debugger stops just before and just after every call to EVAL, At cach step the Debugger 

Ii indicate its current condition as follows. If EVAL is recursively entered at level, 2, with input, object, the 
vay will bes 
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n> — object 

(where object is ampersand printed), If EVAL is returning froin level, n, with result, object. the display will be: 
a= object 

(where object is ampersand printed), 


The Debugger will stop at each such step and wait for directions. , here are four interrupt characters that 
may be typed to proceed further in the program: tH, 10, tR and tA. ‘They cach take an optional prefix 
argument that serves as a repeat count 

™ 
causes the Debugger to perform the next step of the current evalation. 

0 
auises the current abject to be completely evaluated without any one-stepping and then stops with the result 
oF that evaluation, 70 is useful for stepping over COND predicates thot you know will not succeed, or more 
generally. uninteresting parts of a program, 

tA 
is similar t #0, but specific to the evaluation of the argument list ofa FUNCTION. PROG, or REPEAT. Typing 
+A during such evaluation allows the rest of the argument list to be evaluated without one-stepping and then 
stops before evaluating the body ofa FUNCTION, PROG, of REPEAT of retuming ofa result. 

m 
is most effectively used in a REPEAT or PROG loup. ‘Typing *R causes evaluation ta proceed unuil control 
returns to the point in the body of the REPEAT /PROG at which +R was typed. It thus allows you to go once 
around a loop. 


It should be noticed that, when stopped at one of these steps, you can examine and modify program 
variables, do a FRAMES or FAS, EDIT FUNCTIONS and set breakpoints, and in general perform any valid 
MOL operations, Also, when you stop, the LVAL of the ATOM LAST-OUT will be set to the ubject the 
Debugger last typed out. This is useful if the & performed by the Debugger did not show a particular detail 
that you are interested in, 


Use the interrupt character TE to leave the ON state and return to the READY state. Use the interrupt 
character + to leave cither the ON state or the READY state and return to the OFF state. When leaving the ON 
jtate sts described, the execution currently heing one-stepped will be finished in the usual manner, 


The function REPAIR attempts to fix any errors in the Debugger that you might happen to invoke. These 
crrors are casily distinguished since they never occur in MDL'S MAIN PROCESS. ‘Therefore, you will see: 
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LISTENING-AT-LEVEL m PROCESS 
{where m is not 1). REPAIR ums off the Debugger and returns you to running in the MAIN PROCESS (no 
longer one-stepping). Hecause REPAIR turns off the Debugger, you must do <DEBUG> again if you wish to 
try any further one-stepping. 


3.5.1, MDL Debugger Command Summary 

<USE "DEBUGR™> loads the Debugger. 

<DEBUG> makes the Debugger ready. 

1B begins one-stepping. 

1N performs the next step of the computation. 

10 steps completely over the next computation, then stops and continues one-stepping. 
‘+A evaluates the arguments of the current object then stops and continues one-stepping through the body. 
‘+R continues evaluation until you return to this point. 

*+€ ends one-stepping. 

1Q quits one-stepping and makes the Debugger uiready: (turned off), 

<HELP> prints a command summary. 


<REPATR» attempts to repair any Debugger errors you might invoke. 


3.5.2, MDL Debugger Special Features 


‘The following flags have special importance to the Debugger: 
sINDENT-INC 


is the amount by which to indent for cach level (by default 2 spaces). 
 INDENT-MOD 


The indentation-level is the real level taken modulo this number. The default is 10. Indentation ‘restarts’ 


when level gets here. If you don’t like this feature, make the number large. 
 INDENT-DIF 


is the minimum amount of free space to reserve on euch line that indentation mus not touch (by default 20). 
‘Merefore at level L the indentation is exactly: 
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MIN <* ,INDENT-INC <MOD .L .INDENT-MOD>> 
= 13 ,QUTCHAN> , INDENT-DIF>> 


.OUT-FAST 
if true the Debugger will nat stop when leaving a level with a result. The default is T. 
,OUT-UNIQUE 


if both this and previous flag arc true successive ‘outs’ ofthe same item will not be displayed (defuults to 1). 
«SELF-FAST 
if true the Debugger will not stop when cntering a level with an object which EVALS to itscf (c.g. ATOMS. 
FIXes. STRINGS). The default is T. ‘The display will be: 
nz object 
.FORM-FAST 
‘true the Debugger will not stop when entering 2 level with any of the “short” FORMS (cg. <>, .FO0, ,BAR, 
ANYTHING), ‘The defile is T. The display will bet 
ni FOO = hal 
\ny of these flags can be SE TGed by yout to tailor the Debugger to your own tastes, 


3.6. Execution Tracing 
The "TRACE" PACKAGE provides a facility for observing the arguments and returned values of selected 
FUNCTIONS and RSUBRs. It is possible uv print the arguments on entry to the function. print the value 
rotwrned, and to break on entry ww and exit from the function. .\il actions may be performed conditionally. 
Vw load TRACE, type 
USE *TRACE> 


3.6.1. Using TRACE 
TRACE is invoked by 
GTRACE what options» 


what is cither an ATOM or a LIST of ATOMS, naming the things to be traced. These may include SUBRs, 
FUNCTIONS, and RSUBRs: however. anything which is traced must EVAL all of its arguments. options 


ipecifies the behavior of TRACE with respect to the specified function. There are five switches, as follows: 
IN-BREAK 


means byreak (cause a Mbt. ERROR) before calling the function. Nonnally off. 
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IN-PRINT 


means & function arguments on entry. Normally on. 
OUT-PRINT 


means & function value on exit. Normally on, 
OUT-BREAK 


break after executing the function call. Normally off, 
VERBOSE 


‘Means & the arguments to the function one per line. ‘This is useful if the arguments are long. Normally off. 


‘To cause a given option Ww be unconditionally on, include jts name (an ATOM) in the upsions TUPLE. ‘To 
cause an option to be imconditionally off, include a two-clement LIST. composed of the option name and a 
FALSE. If the second clement of the LIST is neither FALSE por an ATOM. it will be EVALed cach time 
TRACE examines the setting of the given option for the function. This 


lows conditional breakpoints, for 


example. 


‘Thus: 
<TRACE FOO (OUT-PRINT <>)> 
will cause FOO's arguments to be printed on entry, bul the value will not be printed. 
<TRACE FOO (OUT-PRINT "<G? <TIME> 4.0>)> 
‘will cause printing of the value after four seconds of cpu time have been used. Printing of the arguments will 


occur each time F00 is called. 


UNTRACE turns off tracing of the specified functions: 
SUNTRACE what:atom-or-list> 
What defaults to a LIST of all functions which have been traced. 


3.6.2. Understanding TRACE 

TRACE works by CHTYPEing the specified functions to new types which have an APPLYTYPE associated 
with them. "This means that one cannot trace calls to RSUBRs or RSUBR-ENTRYs which are already linked, 
In addition, it means that UNTRACE must be used Ww get the old value back. ‘Ty determine the status of a 
function with respect tu tracing, say 

<GET applicable TRACED 

This returns FALSE if applicable is not traced; otherwise, it returns an object which describes the settings of 
the various uptions. ‘The object has a PRINTTYPE which associacs the name of each option with its setting: 


36 Exccution 'l'racing 


6 The MIDI. Programming Environment 


<GET ,FOO TRACEDS 


Foo 

IN-BREAK: #FALSE () 
IN-PRINT: 

QUT-PRINT; <G? <TIME> 4.0> 
OUT-BREAK: #FALSE () 
VERBOSE: #FALSE () 


Individual settings for a particular function may be changed by PUTting into this structure: 
<PUT <GET ,FOO TRACE> ,IN-BREAK T> 


causes a break whenever F00 is called. 


3.7. Monitors 

A comnwn problem in debugging is the mysterious ‘clobbering’ of some value ur clement of a data 
winicture, MDI has imbedded in it a mechanism for triggering interrupts on references. cither for reading or 
writing. to values of variables and clements of structures. 


The "MONITOR" PACKAGE is designed tw be a readily accessible user interface tw these “READ” and 
“WRITE” interrupts in the MDI. interpreter. 


‘To obtain "MONITOR, 
<USE "MONITOR™> 


There are three basic kinds of ‘things’ which can be monitored: values of ATOMs, clements of 
STRUCTURED (the TYPE of the clement is not important), and ASSOCIATIONS. 


For ATOMs, the LVAL or the GVAL may be monitored. If the LVAL is to be monitored. ine ATOM must be 
ASSIGNED?. Wor the GVAL, the ATOM must be GBOUND?, If these conditions cannot be met, a monitor 
cannot be generated. 


For STRUCTUREDs, the monitor is on the nth clement, where » is specified when the monitor is created. 
Remember, the monitor is on a slot of the STRUCTURED, not on the contents of that slott 


For ASSOC IAT IONs, the monitor is on the association itself, 


3.7.1. Monitor Internals 
This section expands on the discussion of monitors in the MDL. document itself (3}, 


Mb, defines two types of monitors: Read and Write. “These arc implemented In the language by two 
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interrupts, READ!~ INTERRUPTS and WRITE!-INTERRUPTS, respectively. In addition, the "MONITOR" 
PACKAGE can allow read-write monitors. The “MONITOR™ PACKAGE is at base a sct of functions to create 
and handle these interrupts. A monitor is triggered in the following cases: 


Read monitor: 
For LVALs~ via LVAL 
For GVALS~ via GVAL 
Vor STRUCTUREDs ~ via NTH 
For ASSOCIATIONs-~ via GET and GETPROP 


Write monitor: 
For LVALs~ via SET or "AUX" bindings 
For GVALS ~ via SETG 
Vor STAUCTUREDs ~ via PUT, SUBSTRUC 
For ASSOCIATIONs-~ via PUT and PUTPROF 


Note that PUTRESTs of LISTs which may alter the th clement of 
clement of the LIST and therefore do not cause a write monitor to trigger. 


LIST, do not access the old nth 


Internally, MDI. performs monitoring on LOCATIVEs to STRUCTUREDs. In fact, LVAL and GVAL are 
really pointers to an internal structure. ‘This need nox concern the user except in the case of LVALS of ATOMS, 
In this case, MDI. will monitor a LOCATIVE to shat (exactly that unique) hinding of the ATOM. When that 
binding becomes invalid, or more precisely, 

<NOT <LEGAL? Jocative>> 
a function in the "MONITOR" PACKAGE will make the monitor vanish. {legal monitors print as 
MONITOR [ILLEGAL] (if you ever geta pointer to one), Remember that if you want to monitor the LVAL 
of an ATOM bound in a FUNCTION (or PROG, ctc.), you must create a new monitor cach time, as a new 
binding is created cach time. One way to do this is to edit into the FUNCT ION a call 1o MONITOR (sce below) 
after the ATOM becomes ASSIGNED?. Fortunately, EDIT (see section 3.2.2.9) has commands to do exactly 
that. 


3.7.2. Creating MONITORS 
Creation of all monitors is done through a call to MONITOR (which reuurns an object of TYPE MONITOR), 
as follows: 
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<MONTTOR pecsiring 
object 


where 
predicate 
sodostuple > 
where: 
ype isone of *READ™, “WRITE*, of "RW". 
vobject ts cither an ATOM or a STRUCTURED, or an ASSOCIATION item. 


where is cither LVAL or GVAL (if object is an ATOM) ur a FIX, (if object s u STRUCTURED), or an 
ASSOCIATION INDICATOR. 


predicate ts something which is EVALed Ww determine whether the monitor is tw be triggered: this defaults to 
F. The "MONITOR™ PACKAGE defines three variables which can be referenced in the test: 


OLDVAL is the old value of the object monitored. 

NEWVAL is the new valuc of the object monitored. 

MONOBS is the object monitored (ATOM or STRUCTURED). 

Hore ralue means LVAL. GVAL. ur clement. Obviously, NEWVAL is not set for “READ™ monitors. 
sodo is uny number of things to be EVALed and PRINTed when the monitor is triggered. 


Note that predicate and todo arc identical to the analogous arguments of the EDIT BK command. 


3.7.3, Monitor Events 
When a monitor is triggered, the following is printed (remember the predicate is evaluated before this), 
und then LISTEN iscalled. To continue, <ERRET >. 


Read: 
**READ of where of objeci** 


todo2 = result? 


Write: 
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S*WRITE of where of objecr** 
01d value: oldval 

New value: newval 

todol = result! 

todo2 = result? 


A slightly different first line format is used for associations. 


3.7.4. Killing Monitors 
Killing a MONITOR is accomplished by calling KILL-MONITOR as follows: 
<KILL-MONTTOR monitor> 
or 
<KILL-MONITOR pipe object where> 
In the latter case, 1ype, object. and where are as given in the original call to MONITOR. 


‘To kill all MONT TORS, use 
<KILL-ALL-MONITORS> , 


3.7.5. Other Monitor Routines 
<MONOBI mionitor> 
retums the object monitored. 
<MONSPEC monitor> 
returns the where of the MONITOR. 
<CLEAN-MONITORS> 
flushes invalid MONITORS from the MONITOR LIST. ‘This is done internally and need not be called 
routinely. 
sMONITORS 
isa LIST ofall current MONITORS. 


3.7.6. What You Can't Do with Monitors 
‘You can’t monitor the LVAL of something BOUND? but not ASSIGNED?. F.g., 
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“DEFINE WRONG ("AUX BAR) 
<MONTTOR "READ" BAR LVAL> 
vob > 


Yow can't expect compiled code to cause monitors to be triggered. Naturally, you can’t place monitors in 
compiled code: however, a compiled reference wo a monitored ATOM will not usually cause the monitor to 
trigger either, 


3.8. FINDATOM 

‘he “FINDATOM" PACKAGE is intended to reduce the problems caused by multiple OBLISTs and 
lengthy ATOM naines in Mbt. It allows one to find all ATOMs whoss PNAMEs match some specification, which 
faved not be exact; in addition, one may place constraints an the values of the ATOMS found, 


F-INDATOM is invoked as: 


FINDATOM specsircstring 
searchlist 
constraints 
outobl:list> 


speesi¢ 's W STRING describing the PNAMEs of the ATOMs one wishes to find, ‘Three special characters are 
recognized in this SV RING: 


+: matches anything, including an empty string 

+: matches any single character 

10: quotes the following character 

Search strings may be an arbitrary concatenation of normal and special characters. For example; 
**S0M*": matches any ATOM containing "SOM" anywhere in its PNAME. 


**=S0M*"; matches any ATOM containing “SOM" in its PNAME, provided that at least one character 
precedes the "SDM". 


"ge": matches any ATOM with PNAME ***. 
"**: matches any ATOM. 


If 19 is the only special character in the string, it need not be quoted: 
PNAME *Q*. 


*1Q" scarches for ATOMS with 


searchlist specifics the OBLISTs to search. Possible values are: 
FALSE (): search all OBLISTs in .OBLIST 
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WFALSE (oblists-ur-forms): scarch all but the OBLISTs specified. 
oblist: search only this OBLIST. 

list-of oblists: search only the OBLISTs in this list. 

else: scarch all OBLISTs. This is the default. 


constraints is a TUPLE describing the value of each ATOM found, It may consist of any number of valid TYPE 
names. along with arbitrary structures and the following special objects: 


T: if present, overrides any uther constraints; if no other constraints are specified, this is assumed, Any 
ATOM matching specsir will be accepted, 


ANY: overrides any constraint other than T. Any ATOM matching specstr which has a value (cither GVAL 
Or LVAL) will be accepted. 


>: any ATOM which has no value will be accepted, Note that giving both ANY and <> is equivalent to 
giving T. 


LINK: any LINK will be accepted. 


If other constraints are provided, they work as follows: all valid TYPE names given (ones for whom 
VALID-TYPE? retums T) are stored in a structure; when a value is encountered. its TYPE is MEMQce 
‘on this structure. If the ATOM does not succeed here, next checked against the “arbitrary 
structures.” 


Anything in constraints which is neither one of the above ‘special objects’ nor a valid type is treated as 
DECL specification. All such objects are put in a FORM sturting with OR, which has the effect of 
generating a single DECL specification, When a value is found, DECI.? is called with the value as its 
first urgument and the generated FORM as its sccond, If DECL? rewmns T, meaning that the FORM is 
valid as a DECL for the VALUE, the ATOM is accepted. 


Haamples: 
ATOM FALSE "<LIST [REST FIX]> 


specifics that any ATOM accepted must have cither a GVAL or an LVAL which is of type ATOM or 
FALSE, or which isa LIST of FIXes, 


"OR ATOM FALSE> ‘<LIST [REST OBLIST]> 
specifies that any ATOM accepted must match the DECL 
<OR COR ATOM FALSE> <LIST [REST OBLIST]>> 


outobl, if present, is 2 LIST of OBLISTs which is the LVAL of OBLIST when F INDATON prints things. ‘Thus, 


‘one may force all ATOMs to be printed with full trailers by providing an empty LIST here. ‘he last 
argument given to FINDATOM, provided itis 4 LIST, is assumed to be owiobl. 


FINDATOM prints the name of cach ATOM it accepts, followed by the STRING "Gass igned™ and the 
type of GVAL if the ATOM has one; this will be followed by the STRING “Ass igned™ and the type of the 


38 FINDATOM 


2 The MDI. Programming Environment 


LVAL if the ATOM has one. It prints the number of ATOMs found when it finishes. 


3.9. "PINFO" 
"“PINFO™ is an informational PACKAGE. It is used to examine the OBLISTS of the PACKAGEs loaded into 
an MoI. ‘There are two major entries in PINFO. 


<PCK-INFO. package:string 
intenal?:boolean> 


Hoth arguments w PCK-INFO are optional. If neither argument is given, the names of the PACKAGES loaded 
into the Mbt. are listed. fa package is given, the contents of the package's ENTRY OBL IST are listed, as well 
as information about the VALUE of each ENTRY. If inicrnal? is provided and non-FALSE the contents of the 
internal OBLIST are also fisted. PCK~TNFO prints an error message if package is not loaded. 

<PCK-USES packuge:siring> 
lists the names of PACKAGEs USEd by package or returns a FALSE if package is not loaded. 


3.10. Debugging in a Run-time Environment 

A fairly common occurrence when running ‘debugged’ code is to find that if was not after all completely 
debugged. It is useful to be able to load interpreted versions of some FUNCTIONS in a PACKAGE into the 
compiled environment for debugging. “DFL", “ROFL, and “UNLINK” are PACKAGEs written to simplify 
this procedure. 


3.10.1, DFL 
‘The “DFL" (‘Debugging Fload') PACKAGE js a set of routines for loading and dumping of small numbers 
of FUNCT IONs from a larger file. It is useful in debugging already running systems, or ones which have not 
been GROUP-LOADed. To get "OFL™ 
USE "DFL™> 
“The main entry of the "DFL" PACKAGE is DFL: 
<DFL func-names file-name:string unlink?:boolean> 
where all arguments are optional and 
fane-names is the namets) of the DEF INEd FUNCT TON(s) to be obtained from this file. It may be an ATOM, a 


‘STRING, or a structure of ATOMs or STRINGS; if ATOMS are given, their SPNAMEs arc used. ‘Ihe default is 
the argument last given to DFL oF ROFL. 


file-name is the file to obuins the FUNCT LON(s) from. ‘The default is the last file DF Led or RDFLed. An ATOM 
‘may be given, in which case its SPNAME is used for the first file name. 


unlink? If this is uc, and if one or more of the values replaced by the DF Led FUNCT IONs were RSUBR or 
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RSUBR-ENTRYs, the reference VECTORs of all RSUBRs, including pure ones, will be scarched for 
‘occurrences of the old value; such occurrences will be replaced by the ATOM. ‘This is the inverse of 
RSUBR-LINKing. Pure structures will be unpurified; this does not change their address in core, but 
simply makes the page they live in read/write. 


In the normal case, if an RSUBR or RSUBR-ENTRY is being replaced, unlinking will occur automatically in 
garbage-collector space only if RSUBR-LINK is T. Also, remember that unlinking is not the same as 
substituting: only RSUBRs stored at top level in reference VECTORs are found: if the old value itself was in a 
‘structure (such as a dispatch table), it will not be replaced. 


3.10.2. RDFL 
ROFL is similar to DFL but is fur reloading RSUBRs rather than FUNCTIONs. RDFL is contained in the 
PACKAGE "ROFL". 
<ROFL func-names file-name unlink? glue?> 
‘The first three arguments are as for DFL. ‘The only difference between ROFL and DFL (barring the effect of 
the fourth argument) is that ROFL scarches in the file for“<SETG * rather than “<DEFINE 
glue? If non-FALSE, ROFL will READ and EVAL the next object in the file following cach RSUBR read. This 


will in the normal case obtain the “glue bits’ for the RSUBR (sce section 6.1). ‘The default for glue?is 
<AND CASSIGNED? GLUE!- > .GLUE!- > 


‘This is the FORM uscd in NBIN files to determine whether ghuc bits should be kept. 
Note that RDFL will work to reload any SETGed object, not just RSUBRs. 


RDFLing an RSUBR-ENTRY docs not work and may well be fatal: you must RDFL the RSUBR in which 
the RSUBR-ENTRY isan entry, as well, 


3.10.3. UN-DFL 
UN-DFL is for writing out DF Led FUNCT IOMs after EDITing. 
SUN-DFL qloms filnam force?» 
‘atoms is an ATOM oF a list of ATOMS, which will be UN-DF Led. “The FUNCT IONs defined must all be from the 


same file, or UN~DFL will not work. UN-DFL can only UN-DFL things which were previously loaded by 
DFL. 


Anam he default is the file the ATOMs originally came from. 
force? Normally. UN-DFL will object if there is a version between the file the FUNCTIONS came from and the 


file which UN-DFL will create: it Uhinks it will Tikely destroy useful information. Providing an ATOM here 
causes this scruple to be ignored. It is almost always unwise to do so. For cxample: 
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<DFL (FOO BAR)> <UN-DFL FOO> <UN-DFL BAR? 
will cause UN-DFIL to fail. Moral: OFL and UN-DFL your FUNCT IONs together. 


3.10.4. UNLINK 

The “UNLTNK" PACKAGE contains three entries: UNLINK, PURE?, and UNPURIFY, UNLINK Is 
sometimes called by DFL; PURE? and UNPURTFY are goxx! ways to Iburatively defeat the safety “interlock of 
Mol. 


UNLINK is used to unlink RSUBRs afler they have been linked. (See the discussion of RSUBR-LINK in 
BD. 
SUNLINK gioms pure?> 


atoms is a list of the ATOMs tw be unlinked, or a FALSE, meaning unlink every RSUBR in the MDI, oF a 
group-name, meaning unlink calls to all FUNCT TONs and RSUBRs in the group. 


jure? is optional and defaults to FALSE, but if true, even pure RSUBRs will be scarched. UNLINK 
examines all the OBLTSTs in the Midi, louking for RSUBRs; ifan RSUBR cxists only in a structure, and not at 
top lovel in any RSUBR’s reference VECTOR, it will not be found. 
UNPURTFY pure-object:any> 


PURE? takes an object and determines if the right half of the value word is greater than the number 
contained in the MDL location PURBOT. which is the lowest pure location in MDL. Ergo, ‘Is the object | gave 
you pure? Itis only meaningful for structures. 

CUNPURIFY pure-object;any> 


LUMPUR TFY takes a single argument. which must be of PRIMTYPE VECTOR or UVECTOR (i... it must have 
an AOBJN pointer for its value word). It causes the pages in which that object lives to become impure, and 
rewums T. 


Tecause there is no way on ITS to make a read-only page an impure page directly, the following algorithm 
is used by UNPURIFY: 

|. Is the object pure, according w PURE? If not, leave. 

2. ISUNPURTFY-PAGE ! ~ TUNL INK GASSIGNED? If not, get a page from the interpreter, and SETG 


the aforementioned ATOM to its number, I.c., the page is more of less permanently taken for use 
of UNPURIFY. 


3, For cach page occupied by the object: a) If the page is alrcady impure, do nothing: b) otherwise, 
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‘map the page on top of UNPURIFY-PAGE: c) create a new. impure page where the old page was, 

4) copy the contents of UNPURI FY~PAGE back to the old, now impure page. 
‘Thus, no pointers are changed: as far as MDI. is concerned, in fact, nothing has changed. ‘The unpurified 
pages are still pure, according to its page map. However, you may frecly change the unpurified object. 


Iyour change to the newly unpurified object consists of PUTing a pointer into garbage-collected space 
into the object, you may lose completely unless the pointer points to a froven object. The MDI. garbage 
collector does nor examine unpurified objects. UNLINK can Only use UNPURIFY because all ATOMS 
referenced by pure RSUBRs are indeed frozen. 


For the above reason, use of UNPURTFY is not recommended for the general user. 


3.11. CRITIC 

"CRITIC" is a PACKAGE designed to aid the user in debugging (and perhaps increasing the efficiency of) 
his programs. It accumulates and prints in a readable format information about the interactions of the various 
FUNCT IONs (and LVALs and GVALs) in a group. It also warns the user about various conditions it considers 
to be cither non-optimal or erroneous, such as incorrect use of SPECIAL, furgctting to QUOTE some structure, 
and so on. Like most critics, 


"CRITIC" say 
SUSE "CRITIC"> 


is sometimes wrong, but it tries to perform a useful service. Tu load 


‘There are two major entries, one of which prints more information than the other. 


<CRITIC growpname 
oulput-file> 


where group-name is the ATOM retuned by 2 GROUP-LOAD, and the optional owiput-file is a STRING giving 
the name of the file to output to (by default with second file name "CRIT1C"). This can also be a CHANNEL 
if you are planning to do several CRITICS into one file. CRITIC prints information about interactions 
among the FUNCT IONs in a group (as described below). 


<CRITIC-NOTES group-name 
‘oulput-file> 


is similar but only prints ‘errors’ and ‘warnings’ -- things that might be problems with the FUNCT IONs in the 
group. 


‘The output format (for cach FUNCT TON and for the group as a whole) is as follows: 


function (abject number of function in group) 


Called-by: a list of all the functions which call function 
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Ca115: a list of all the functions called by function 
SETG: external globals SETGed by function 
GVAL: external globals referenced by function 
SET: external variables SET by function 
LVAL: external variables referenced by function 
SPECIAL: variables declared SPECIAL by flunction 
USE~DATUM: DATUMS used by function 
‘The above table is printed by CRITIC but not by CRITIC-NOTES. “External” as used above means 


“External to function’. 


CRITIC-NOTES and CRITIC both print information about possible defects or crnors in cach FUNCTION. 
“These can be any or all of the following (explanations follow where needed). 


3.11.1. Global problems with the Group 
FLOAD in file. 

‘This fs pretty minor: FLOADs at top level are discouraged if you can avoid them, 
BLOCK or ENDBLOCK at top level in PACKAGE. 


PACKAGES should not have to resort to this. 


atom-name: MANIFESTed structure, 


“The ATOM given is a structure but was MANIFESTed. Since a MANIFEST is copied within the reference 
VECTOR of any RSUBR that uses it, itis usually not a good idea.. 


ENTRYs not bound, assumed locals: alonrlist 


“The ATOMS given were made ENTRYS in the PACKAGE, but were not bound, so CRITIC has assumed they 
are locals, for lack of something better to do. 
Packages USEd but never referenced: packagenames 

“These PACKAGES were in USE statements but no ATOM was ever found which fell on their OBLISTs. 


There will sometimes be incorrect entries in this list if you USE a PACKAGE which sets up a funny ENTRY 
OBLIST (RPACKAGEs included) or no OBLISTs tall. 


Internal functions unused: atonrlist 


“These are FUNCT IONs DEF INEd but apparently never referenced and not entries. There will sometimes 
be incorrect entries in this list if you have FUNCT IONs invoked only by funny dispatching methods, such as 
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APPLYing or EVALing an clement of 2 structure. 


Internal globals unused: atonrlist 


ATOMs SE TGed at top level but never referenced. 


Internal manifests unused: aiom-lisi 


ATOMs SETGed and MANIFESTed at top level but never referenced. 


3.11.2. Parameter list problems 
ATOM atourname used twice in parameter list. 


‘The ATOM named was bound twice in the same parameter LIST within the FUNCTION. Mbt. doesn’t 
worry about this, but you might. 


Untasteful re-use of ATOM avm-name in ROOT. 


‘An ATOM was bound which happened to be in the ROOT OBLTST and happened to have a GVAL that is @ 
‘SUBR or FSUBR. ‘This is reported because the ATOM will have to be unpurified, which is expensive, 


"BIND" illegally located. 


‘A “BIND™ was found other than at the beginning of a parameter LIST. 
*CALL"/*ARGS" illegally located. 


A “CALL” or “ARGS” was found after the “AUX* in a parameter LIST. 
"OPTIONAL" illegally locates 


“OPTIONAL” was found after “AUX" in a parameter LIST. 
"TUPLE" illegally located. 


"TUPLE* was found after "AUX" in a parameter LIST. 


atom “AUX” 41 legally QUOTE. 


‘The ATOM named was given as a quoted argument in the "AUX" part of the parameter LIST, 


External locals set but unbound and unDECLed: atonrlist 


External locals set but unbound: atomlist 
‘Two different classes of hacking an external local. In both cases it means that the ATOMs did not appear to 
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be improperly SPEC TALed, since no onc bound them higher in the call tree (or at top level), ‘These are most 
often indications of misspelling or forgetting to put a temporary in the parameter LIST. 
External locals used but unbound and unDECLed: atonrlist 
External locals used but unbound: atom-list 

‘A reference to an external local which was not bound anywhere is probably a misspelling of a SPECTAL 
‘bound elsewhere or the result of forgetting to put the ATOMs in the FUNCT ION’s parameter LIST. 
External locals set but unDECLed: ofomrlist 


External locals used but unDECLed: atom-list 


‘An external used but not DECLed usually means that the compiler will produce poorer code. 


3.11.3. Unused ATOMs 
Argument unused: aionlist 
‘The arguments listed were never referenced. 


Unused: atomlist 


‘The ATOMS listed were bound at top level of the FUNCT ION and never referenced. 
Unused in PROG: atom-list 


‘Similar to the above, but the ATOMs were bound 


Unused in REPEAT: atonrlist 


‘Similar to the above, but the ATOMs were bound within a REPEAT. 
Unused in FUNCTION: atonrlist 

‘Similar to the above. but the ATOMs were bound within a nameless FUNCTION, such as the second 
argument to a MAPF/MAPR, 


Unused SPECIALS; alonrlist 


‘The same as above (including * ... in FUNCTION’. ctc.), except that the ATOM was SPECTAL. ‘This 
message results from really looking down the call tree, so it Is more accurate about this problem than the 
compiler, which only looks at the FUNCT ION in which the ATOM is bound. 
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3.11.4. Function calling errors 
Calls undefined function aiom. 
‘The FUNCTION calls an undefined FUNCT ION (undefined at the time CRITIC ran). 
Calls fiction with too few arguments. 
Calls function with too many arguments. 
External FUNCTION function 


‘The FUNCT ION named is called but doesn’t seem to fall on any of the OBLISTs associated with the group. 


3.11.5. SPECIAL/UNSPECIAL problems 
SPECIALS never used as SPECIALS: «om-list 
‘The ATOMs were made SPECIAL but never used outside the FUNCTION in which they were bound. 


atonrname 4 unused or should be SPECIAL. 
A very specific error which means that the ATOM given (always one of INCHAN, OUTCHAN, or OBLIST) 


was bound but never referenced within the FUNCTION, and was not SPECIAL: Fither you bound it for 
effect and forgot to SPECIAL it, of you didn't need to bind it. 


‘aiom unbound in paths: —path-list 
Ifthe FUNCT ION is called by one of the paths given, the aium will be unbound. A path is just alist of calls 


CRITIC has found are possible, such as (FOO BAR BLECH), meaning "F00 is called by BAR which is called 
by BLECH’ 


The ATOM aiom used in fen! should be special in fen2. 


“this note will appear with both FUNCTIONs mentioned, It means that atom is referenced in fen! and the 
nearest FUNCT 10N that binds it and calls down to fen! is fen2. 


3.11.6. DECLing problems 
RSUBR has no DECL. 
FUNCTION has no DECL. 


Parameters not DECLed: aiomlist 


‘The ATOMs given were bound but not DECLed in the parameter list of a FUNCT ION, PROG, or REPEAT. 
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No DECL in DECL for: atonrlist 


“The ATOMs in the afonr-list given had no associated declarations. 


NEWTYPE not DECLed: typename 


‘A NEWTYPE of a structured type was made but no DECL argument was included. In a structured 
NEWTYPE, including a DECL of the interior can greatly increase the efficiency uf compiled cade. 


T1 legal DECL: atonrlist dec! reason 


‘The DECL puir given had illegal syntax fur the reason given. ‘These can include: 


“Not a legal type": An object appeared ina DECL that was not an ATOM, FORM, or SEGMENT. 


“Type-name not a type: atom": Something other than a type-name or special symbol (such as ANY) 
appeared where a type was expected. ‘This is sometimes caused by not having your environment 
completely set up when CRITIC is run, 

“FORM/SEGMENT too short": \ FORM/SEGMENT construction of only one element was found. 

"SPECTAL/UNSPECIAL with three or more elements” 

"Bad PRIMTYPE type: Thetype given in a PRIMTYPE was ot a type-name, 


“PRIMTYPE with three or more elements” 


"Bad type of structured type”: The type-name given as the type of a structured type was not a 
type. Forexample, <FOO FIX> where FOO isnot atype. 


"Bad BYTES specification”: A BYTES spccification was not of the form <BYTES fix fix>, or the 
byte size was greater than 36. 


"BYTES DECL too short”: A BYTES construction of only one clement was encountered. 

"BYTES DECL too long”: A BYTES construction of more than three clements was encountered. 
"VECTOR in OR specification": An NTH/REST/OPT construction was found at top level of an OR, 
"Nth/REST/OPT too short": A onc-clement NTH/REST/OPT. 


"Only REST or OPT may follow OPT": Something other than a REST or OPT was found after an 
opr. 


"REST must terminate DECL™: Something was found aftera REST in the DECL. 
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3.11.7. Miscellaneous 
Possibly should be QUOTEd: siructure. 


‘The structure given will be =? to itself if EVALed. CRITIC lists these under the assumption that you 
‘might have forgotten to QUOTE a structure that should have been. It says “possibly” because you obviously 
want to build new structure sometimes. One way to do this without offending CRITIC is to build new 
structure with explicit calls to LIST, VECTOR, ete. 


3.12. Program Environments 
Vhe ENV PACKAGE makes it casier to load programs into different environments. It allows certain actions 

Ww be taken during londing only if given ‘eature’ is present, ENV has three ENTRYs. and ts preloaded. 

<FEATURES featuresstuple> 
Ifgiven no arguments, FEATURES returns the current feature LIST. If ts first argument is not a FALSE, the 
arguments are aulded to the feature LIST. If the first argument is FALSE, the remaining arguments are 
removed from the feature LIST. ‘Thus, 

<FEATURES "COMPILER"? 
Says that we are currently in a compiler. All of the “feature arguments may be cither STRINGS or ATOMS; 
internally features are stored us STRINGS to avoid OBLI'ST problems. 

“FEATURE? features:tuple> 
returns T if any of its arguments is on the feature LIST. 

<EVAL-WHEN fearures 


uses the first argument tw devide whether to evaluate the remaining arguments, 


Seatures specifies which feature(s) to look for. It may be a single feature or a LIST of features. In the latter 
case, ifthe first clement is a FALSE, what is checked for is the absence of the features listed, Note that this 
‘argument is often a LIST created out of arguments to FEATURE?. 


‘consequences are things to be evaluated only if the features are present (or absent, in the FALSE case), 


For example, 
<EVAL-WHEN GLUE <SETG FOO 1>> 


would perform the SETG only if it’s evaluated in a GLUE (or some other environment defining that feature), 
<EVAL-WHEN (<> COMPILER) <SETG BAR 2>> 


would not perform the SETG in the compiler environment 


‘Unfortunately, the ENV PACKAGE is a relatively recent innovation, and so many programs do not sct up 
‘appropriate environments. 
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4. The Library System 

A coherent unified library system serves to-facilitate the sharing of algorithms and data by imposing 2 
discipline appropriate for the particular environment. ‘The MDI Library System provides: 

— A uniform access method for referring w functions and data outside of the current logical group; 


— Lexical blocking. climinating difficulties arising from ovetlap of names between diferent logical 
Broups; 


— Automatic loading of functions for the user who knows only the name of the function which is 
wanted: 


— A facility whereby funetions which may be necessary only in unusual situations are foaded only in 
the event that they are needed. 


“The Mbt Library System may be divided into distinct parts. ‘These are: 


— The Package System, the collection of routines used to provide lexical blocking for a logical group 
(sce section 2); 


— The ‘explicit’ loading facility, the routines used to explicitly indicate that references are being 
made to a particular logical group: 


— The “implicit” (or “dynamic’) loading facility, the machinery for automutically leading functions 
when they are needed during console interaction. 


4.1, Program Libraries 

In the previous discussion of the Package System and USE (sce section 2.32), we glossed over the 
mechanism by which a PACKAGE is loaded when another PACKAGE (or the user at his terminal) refers to it. 
We will now give the details. 


“There are 1wo types of loading common in Mbi. programming: ‘explicit’ loading, such as USE may 


initiate, and 


plicit’ or “dynamic loading. initiated by attempting to call or examine a function that is not 
currently loaded. 


In the case of ‘explicit’ loading, it is necessary somehow to map the name of a PACKAGE into a file name 
which contains the body of that PACKAGE. ‘The mechanism for doing so must be exible enough to allow 
both ‘installed’ programs (those that have been debugged and submitted to the library) and developmental 
programs to be loaded. It must also be tailorable for special needs, such as libraries for specific systems and 
personal libraries for individual users. 
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In the case of “implicit” loading, the further mapping from the specific ENTRY of a PACKAGE referenced to 
the PACKAGE itself must be performed. It must deal with the case of two ur more PACKAGES cach containing 
an ENTRY with the same PNAME. 


For programs that are ‘public’ or ‘installed’, both of these mappings are performed by a library, A library 
is. file which contains pointers between the names of ENTRYs of PACKAGEs and the PACKAGEs containing 
them, and from PACKAGE and DATUM names to the files containing them. 


‘The standard library is named LIBMUD and lives on a directory named LIBMUD (un ITS) or HOLLIB (on 
‘Tenex/Tops-20), but other libraries. personal or special purpase, may also exist: the mechanisms for creating. 
and maintaining them are the same in both cases. 


4.1.1. Library Searching 

When a PACKAGE is USEd, MD first checks to see if the PACKAGE is already loaded, by looking up the 
PACKAGE name on the PACKAGE OBLIST, If the PACKAGE is not yet loaded, Mint. niust search for the file 
containing the body of the PACKAGE, 


‘When MDL searches, it does so under the direction of a scarch path stored as the LVAL of the ATOM 
L-SEARCH-PATH. ‘This LVAL is a LIST. cach clement of which specifics ‘a place tw look’ for the PACKAGE. 
‘These elements may be: 

“file-name* 
A STRING refers to 

a 
‘An empty VECTOR refers to the <SNAME> dircctory. ‘The dircctory will be searched for files whose names are 
the name of the PACKAGE being loaded (truncated to six characters on ITS) and second names from the 
LVAL ofthe ATOM L-SECOND-NAMES, which is a VECTOR of STRINGs which are possible second names for 
the Mite, 

[ir:string-or false] 
A non-empty VECTOR specifies a directory. The first element of the VECTOR gives the directory as a STRING 
‘or a FALSE, the latter case meaning <SMAME>. If that is the only clement, L-SECOND-NAMES specifics the 
file names to look for. If there are other elements, they should be STRINGS to use in place of 
L-SECOND-NAMES. 


rary file: *L 1BMUD ; L 1BMUD™ for example. 


‘A search path may consist of any number of such clements. The loader will examine them sequentially, 
attempting to find the PACKAGE being loaded. 
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“The initial LVAL of L~SEARCH-PATH (on ITS) is 

("LIBMUD™ "LIBMUD;LIBMUD" [] ["MBPROG"] [“MPROG™ *>"]) 
and on Tenex/TOPS-20, itis : 

("LIBMUD" "<MOLLIB>LIBMUD" [] ["MOLLIB"]) 
‘This instructs the loader to first search the user's personal library (if it exists), then the ‘public’ library. Next, 
search the user's directory for a file whose first name is the PACKAGE name, and whose second name is 
specified by L-SECOND-NAMES. If thot fails. perform the same search on the library directory, and finally 
(on ITS), 1ook fora source version of the PACKAGE on the source directory. 


‘The initial LVAL of L~SECOND-NAMES (on ITS) is 
[°FBIN" "GBIN" "NBIN" *>"] 
and on Tenex/TOPS-20, itis 
["FBIN" "GBIN" "NBIN" “MUD"} 


‘To give a simple cxample of how this mechanism may be tailored for individual needs, consider a 
programmer debugging a subsystem. Ifhe wants his debugging versions of various PACKAGES to be loaded 
befure the installed versions, he CONSes a new clement onto L-SEARCH~PATH so that it contains 

({] "LIsMuO" "LIBMUD;LIBMUD" [] ["MBPROG"] ["MPROG" ">*}) 
{assuming the files with his debugging versions are on the <SNAME> directory). 


4.1.2. Dynamic Loading 

To ease the use of "top level" routines from the console. a feature is provided whereby the Library System 
can loud a PACKAGE of functions automatically when one of the functions which is an ENTRY in that 
PACKAGE is invoked by name. ‘This facility is not available for use by other PACKAGEs of functions, which 
must refer explicitly, vis USE, to PACKAGEs which they require: while a human can resolve the difficulty of 
possible multiple PACKAGEs with ENTRYs of the same name, a program cannot. 


‘When an error is generated because a FORM is evaluated. and the first clement of that FORM is an ATOM 
which has no value, and the particular ATOM is in the INITIAL OBLIST, an crror handler established by the 
Library System determines if there are any PACKAGEs in the current libraries which contain an ENTRY with 
the same name as the PMAME of that ATOM, If there is one such PACKAGE, it is loaded, and the evaluation 
which got the error is continued with the correct value, If there is mare than one such PACKAGE, the possible 
choices are displayed, the user is asked which is the desired PACKAGE, and it is loaded. If there are no 
PACKAGEs with ENTRYs of the correct name, the error is not handled, and so it will fall into the standard 
crror mechanism, ‘This same procedure is also invoked when GVAL is applied to an ATOM on the INITIAL 
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OBLIST and the ATOM has no value. 


4.1.3. USE-DEFER 
It is sometimes desirable to have available functions that are rarely invoked, but are nonetheless available. 
(One example would be certain error handling routines.) 


‘The USE-DEFER function sets up the OBL IST path so that, when a reference is made wy an ENTRY in the 
specified file, the correct ATOM is found, but the PACKAGE is not actually loaded at that time. When a 
fiction at a Later time tries to call the Function which is the value of one of the entries in this PACKAGE, the 
whole PACKAGE will be automatically loaded. USE-DEFER has two constsiints which USE does not. First, the 
PACKAGE musi be in onc of the currently active libraries; it may not simply be a file as in the case of USE. 
Second, no reference may be made to ATOMS which are entries but do not have values which are applicable, In 
other words. ATOMS which are entries because they are data (rather than functions) may mot be referenced 
when USE-DEFER is employed instead of USE. 


Because USE-DEFER utilizes the dynamic loader, which utilizes the ERROR interrupts, USE-DEFER will 
not work in a detnon or any other MDI program which sets up its own error handlers. All such MDL 
Programs should SETG the ATOM L-NO-DEFER w a non-FALSE. which (as explained previously) will cause 
USE-DEFER to behave cxactly like USE. Then, PACKAGEs containing a USE-DEFER can be used without 
modification in demons and the like. 


4.1.4, USE-TOTAL 

USE-TOTAL is analogous to USE, but instead uf splicing in only the ENTRY OBLIST of the PACKAGE, it 
additionally splices in the internal OBLIST. This is usefuul in some debugging situations, as it reduces the 
‘umber of trailers printed and also makes the internal identifiers of the PACKAGE more accessible. 


4.1.5. Translations 

It is uccasionally useful to have more than one copy of a particulir PACKAGE loaded at once. One 
‘example that comes to mind is the case of debugging a debugging PACKAGE. ‘the I ibrary System contains a 
mechanism fur ‘translating’ a PACKAGE name into another one. More specifically, itis possible to tell USE: ‘If 
you ever load the PACKAGE named foo, pretend it was named bar instead.” Note that this does not change the 
searching and loading procedure described above, unly the names of the OBL ISTs and so on used to store the 
ATOMs in the PACKAGE. 


Program Libraries 41 


py 


we 


‘The MDI. Programming Environment 67 


<TRANSLATE old:string new:strine-or false> 
causes the PACKAGE old, when it is USEd, to behave as if it were named new. If new is FALSE, it means that, 
old should be loaded as though it were not a PACKAGE at all; its ATOMs will appear un the DEFAULT OBLIST 
oF <1 .OBLIST> (normally INITIAL). 

SUNTRANSLATE  old:string> 
‘causes any translation of old to be removed, 

<TRANSLATIONS> 
lists all translations currently in existence. 

sL-TRANSLAT IONS 


isa LIST containing all the translations. 


4.1.6. The Library Data File 

In addition to its ability to map between PACKAGES, ENTRYs. and the files which contin them, the library 
Serves another purpose. [Fa user is compiling a function which USES a given PACKAGE. that PACKAGE isnot 
usually going to be run. AM that is necessary is to examine the calling sequences of its functions, and make 
sure that all ‘side-effects’ (such as the definition of new TYPEs) occur. If only these necessary parts of the 
PACKAGE are loaded, a great saving of time and space is effected. 


‘The library data file provides a way of achieving this end. When a PACKAGE is added to the library, more 
information than the list of ENTRYs and the file containing the PACKAGE is collected. In particular, 
MANIFEST GVALs, NEWTYPE definitions, some MACROs, und RSUBR DECLs are stored. Since this is the 
information used by the compiler, one can save a great deal of space and time by using information from the 
library where possible. 


If L-USE-DATF ILE is truc, USE of a PACKAGE will load from the data file if possible, It is impossible if 
the PACKAGE has changed since the data file cntry was created. In those cases, the PACKAGE itsclf is loaded. 
instead. If ,L-ALWAYS-DATFILE is truc, an ERROR will result if the data file entry is outdated; one can 
ERRET T to cause the real PACKAGE to be loaded. 


USE-DATFILE is just like USE, except that it temporarily SETGs L-USE-DATFILE and 
L-ALWAYS-DATFILE to T, 


‘The data file contains, far cach PACKAGE, information for cach interesting ENTRY: MANIFEST GVALs, 
NEWTYPE definitions, RSUBR DECLs, and MACROs. It also has, of course, the lisis of ENTRYs and RENTRYS 
needed by the dynamic loader, It docs not contain other structures, nor docs it contain functions. When a 
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PACKAGE js loaded from the data file, it is effectively USE-DEFERed; if you ond up needing to run part of 
the PACKAGE. it will be loaded dynamically. 


Some PACKAGES can not have datafile entries. Ifa PACKAGE defines MACROs that use data not stored in 
the data file (if the MACRO calls a FUNCTION, for example), the PACKAGE will not get a data file entry: it 
would normally end up being loaded from the file anyway. 


Itis possible For a data file entry w become obsolete (if'a new version of a PACKAGE is created without the 
library entry being updated), or this reason, the library is examined periodically for such entries and an 
attempt is made to update the appropriate entries. 


4.1.7. Run-time Switches 
‘Phere area number of variables which may be set dynamically to tailor the Library System's perfurmance. 
-L-SEARCH-PATH 
as described above (sce section 4.1.1) is a LEST specifying the libraries and directories to look in, and the files 
to look for when trying to luad a PACKAGE. This variable is used by USE. USE-DEFER, USE-DATUM, and the 
dynamic loader. 
-L-+SECOND-NAXIES 
as described above (see section 4.1.1) is a VECTOR of the second names of files to look for when attempting to 
load a PACKAGE from a directory. 
sL-NOISY 
IF the GVAL of L-NOISY is non-FALSE, the names of PACKAGEs and DATUMs are printed whenever they are 
loaded, dynamically or otherwise. This feature may be tutned off by SETGing L-NOISY w #FALSE (). 
L-NOISY has an initial GVAL of T. 
.L-NO-MAGIC 
Dynamic loading may be disabled by SETGing L-NO-MAGIC to a non-FALSE, L-NO-MAGIC has an initial 
GVAL ofa FALSE. 
< L-ALWAYS~ INQUIRE 
If the GVAL of L-ALWAYS- INQUIRE Is non-FALSE, the dynamic loader will always ask the user before it 
Joads anything. ‘The GVAL of L-ALWAYS- INQUIRE is initially a FALSE. 
:L-NO-DEFER 
If the GVAL of L-NO-DEFER is non-FALSE, USE-DEFER will work cxactly like USE. L-NO-DEFER is 
initially SETGed to AFALSE (). 
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4.1.8. Library Utility Functions 
‘A. number of functions exist which allow the user to examine libraries, list their contents, and retrieve their 

entries, All of the functions below except L-PATH and L-OBL accept an optional STRING argument, a 
library specification, If it is defaulted, they operate on the public library, specified by the string "LIBMUD; 
LIBMUD" of *<MDLLTB>LIBMUD". 

<L-LOAD packagessring library:string> 
L-LOAD requires a STRING (the name of a PACKAGE or DATUM) and attempts to load it from library (if 
given) or the current libraries, as per L-SEARCH-PATH. 

<L-FIND function-namessiring library:string> 
L-FIND requires a STRING (the name of an ENTRY), returning « UVECTOR of tworelement VECTORS of the 
form: 


Lrackage-inr which-fimiction-existsstring 
Library-ir which: package-existstring) 


‘This finds all of the entries which have the same PNAME but arc in different PACKAGES. 


“The remaining functions are in the PACKAGE "L", rather than in the PACKAGE "PKG". For cach of 
these, the optional library argument is by default rhe library: that is, "LIBMUD;LIBMUD" or 
‘“<MDLLIB>LIBMUD". 

<L-FILE package-siring library:string> 
L-FILE requires a STRING (the name of a PACKAGE or DATUM) and returns a STRING which is the file 
specification of the file, pointed to by the library, which contains the body of that PACKAGE ur DATUM. 
<L-WHERE package:siring library:string> 
L-WHERE is similar to L-FILE but returns a VECTOR of STRINGS which is the actual complete file 
specification of the file containing the PACKAGE (i.c., the ‘real’ slots in a CHANNEL open to the file). 
<L-LISTE library:string> 
L-LISTE prints the names of all of the entries of all of the PACKAGES in the library. 
<L-LISTP. library:string> 
L-LISTP prints the names ofall of the PACKAGEs and DATUMs in the library. 
<L-COUNTE  library:siring? 
L-COUNTE rewrns a FIX, the number of entries defined by all of the PACKAGES in the library, 
<L-COUNTP. library:string? 
L-COUNTP returns a FIX. the number of PACKAGEs and DATUMs in the library. 
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CL-LISTPE package-yiring library:string> 
L-LISTPE requires a STRING (the name of a PACKAGE) and prints the names of all of its entries. 
<L-PATHD 


L-PATH prints a list of the names of all of the OBLISTs in the uscr’s current OBLIST path. 
<L-OBL alom> 

L-OBL requires an ATOM and returns an ATOM, the name of the first ATOM’s OBLIST. L-OBL isin fact 
<GET <OBLIST? atom> OBLIST> 


4.1.9, Internal Library Functions 
There are several internal functions used for searching libraries (which is, after all, all the 1 ibrary System 

‘ever does), 

<PACKAGE-FIND packaxe-yring libnary:string> 
searches library for package. If there is no such PACKAGE or DATUM jn Jibrary. it rotums a FALSE. 
Otherwise, it returns a STRING, which is the name of the file containing package. 

SENTRY-FINO culryestrine-oratum [brary:siring> 
searches library for PACKAGES containing enry. It returns a FALSE if there arc none, otherwise a LIST some 
multiple of four elements long, where cach set of four clements describes a package containing an ENTRY 
with that PNAME. ‘These clements are: 


package:string is the PACKAGE being described. 

file-name:string is the file-name containing the package. 
‘rpackage?:atom-or false indicates. if non-FALSE. that the package is in fact an RPACKAGE. 
rentry?catont-or false indicates, if non-FALSE, that the entry is an RENTRY. 


<DEFER-FIND package:siring librarv:siring> 
returns a FALSE if the PACKAGE or DATUM is not found, or a VECTOR of five elements describing the 
PACKAGE, 


rpackage?:atonr-or-false indicates, as above, whether the package is an RPACKAGE. 
‘name: string is the name of the package. 

Sile-name:siring is the file containing the package. 

entries:list isa LIST of the PNAMEs of the ENTRYS of the package. 


rentries:list isa LIST of the NAMES of the RENTRY' of the package. 
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“This is all the information about the package that the library contains. 


4.1.10. Library Maintenance 
“The PACKAGE called "LUP™ contains functions used to modify librarics, and to add, update and delete 

PACKAGEs and DATUMs. It should be noted that libraries do not contain the bodies of PACKAGES and 
DATUMs, Rather, they point to files which contain these. 

<LUP-ACT Jibrary:siring> 
requires one argument. a library specification STRING, and activates the library so specified. If the library 
doesn't exist, itis created. In order to protect the library from loss due to system or MDL. crashes, activating 
library for modification copies the library data files and Jocks the library so that no one else may modify it. 
Modifications are made to the copies, which are renamed back over the originals only when the library is 
explicitly deactivated. Obviously, PACKAGES added 1 a library aren't available, even to the person adding 
them, until the library is deactivated. 

<Lup-DCT> 
deactivates the currently active library, 


<LUP-ADD-PACK packasefile:siring 
update?:boolean 
daifile-entry?:boolean> 


package-fite is a file specification of the file containing the body of the PACKAGE to be added. 
LUP~ADD-PACK will find the PACKAGE statement within the file (or complain if it can't). 


updote? is optional, and if non-FALSE. it allows the PACKAGE to update an older version of itself, 
‘something which is not otherwise allowed. Note that, since the library points to the file which contains the 
body of the PACKAGE, that file should not be deleted later, else the library won't be able to find it. 


daifile-entry? is by default T, but if it is FALSE, no entry will be created in the datfile for this PACKAGE. 
Since dutfile entries are generally useful only in the compiler (and similar environments), it doesn't do much 
good to have them for PACKAGEs that are only called from top level (c.g., F INDATOM). 


‘When adding a PACKAGE to the public library, the PACKAGE’s object file should be copied to the 
appropriate library directory (“LIBRMn* on ITS, or “<MDLLIB>™ on ‘Tops-20) and the library pointed at 
that copy of the file. If no library is activated when LUP-ADD-PACK runs, it will activate “LIBMUD; 
LIBMUD™ or "<MOLLTB>LIBMUD™. 
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SLUP-ADD-DATUM name:siring 


filecstring 
update?: boolean? 
{s analogous to LUP-ADD-PACK, adding 2 DATUM to the active library. LUP-ADD-DATUM requires (wo 
STRING arguments, the name.of the DATUM and the specification of the file which contains the body of the 
DATUM. LUP-ADD-DATUM will accept the same optional argument that LUP-ADD~PACK accepts, with the 
same meaning and default. The same restrictions concerning the file « hich contains the DATUM also apply. 
<LUP-DEL package:siring> 
LUP-DEL requires one STRING argument, the name vf a PACKAGE or data set. and deletes that PACKAGE or 
DATUM from the currently active library. LUP-DEL does mot touch the file containing the body of the 
PACKAGE or DATUM. 
<LUP-MOVE package:siring file:string> 
causes the file pointer of package to be changed to point to file. This is a faster vperation than re-adding the 
PACKAGE. and itis intended for situations in which an existing library file has been moved for some reason. 
<LIB-GC library:siring> 
garbage-collects the library in question, if this is required. Garbage-colleetion Is occasionally useful since it 
causes all the clements of cach hash bucket 0 live near cach other in the library file, thus improving 
performance during searches. It also allocates some free storage ir cach page of the file. 


4.2. The Pure-mapping Library 

‘The basic idea behind MDI, pure mapping is to separate out the code part of RSUBRs in compiled 
Programs, ‘The RSUBRs themselves are kept in a file known as an FBIN (sce 6.3). ‘These RSUBRs do not 
contain the code but instead point to a file which contains the code. ‘This scheme has several advantages. 
First, the code can be dynamically mapped in when needed. ‘This allows MDI. to use more code than will fit 
in the virtual address space of the machine it is running on. Secondly, since the code is pure it can be shared 
between several MDLs usin Finally, the FBIN file itself is smaller than a corresponding NBIN file and 
therefore FLOADs more rapidly. 


In the most basic implementation of FBINs, there are three files: the FBIN, the SAV file (which contains 
the code), and the FIXUP file, which contains the information necessary to update the SAV FILE for new 
releases of MDL. As is obvious, this entails a lot of files, and potentially a lot of file directories. ‘The MDL 
Purc-mapping Library reduces this storage overhead by collecting all of the SAV and F IXUP files together. 


‘The scheme uses two large data bases, cach contained in one file. The data bases arc called “SAV’ and 
“FIXUP', ‘These files store all currendy existent SAVs and FE XUPs for al existing versions of MOL. Each data 
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‘base is structured like a file system. There is a main ‘directory’ that points to a number of other ‘directories’, 
cach of which points to a number of ‘files’ inside the data base. In this section the word ‘file’ ur ‘directory’ in 
quotes refers to an object inside a data base. The files containing the data bases are named (on ITS) 
"MUDSAV;SAV FILE" and “MUDSAV;FIXUP FILE". © On ‘Tenex/TOPS-20, they are 
"<MDL>SAV. FILE” and *<MDL>FIXUP. FILE. 


4.2.1. The Demon 

While all Mpts can read from the Pure-mapping Library, there is only one program which can write into 
it. This is a maintainer demon which nins once a day to keep the Library updated. This demon can add ‘files, 
delete ‘files’. and add ‘subdirectories’ to both data bases. 


“To facilitate updating of the Library there iss directory on which to put files wo he added as well as files to 
indicate what is to be deleted. ‘This is the "MUDTMP™ directory on IS and the *<MDLLIB>” directory on 
“Tenex/TOPS-20, Any file on it with the secand name of SAVninn or F IXnnn (where nnn is 2 or 3 digit Mbt. 
release number) will be added to the appropriate data base. If the files "DELETE SAVS™ or "DELETE 
FIXUPS" exist, then they will be used to delete ‘files’ from the data bases. These files must be ASCII files of 
the form 

filename | [SPACE] filename 2 [CRLF] 


An example of a valid delete file is as follows 


NCODGE SAVS3 
ANCODGE SAV53 


‘The demon will ignore any deletion requests for ‘files’ not in the data base. 


“The demon does its work in several passes. The basic passes are the delete pass, the planning pass, the 
update pass, and the salvage pass. The delete pass deletes ‘files’ if either a "DELETE SAVS* or "DELETE 
FIXUPS" file exists on its working directory. The planning pass builds a plan file by examining the working 
directory and calculating where new ‘files’ will be placed in the data bases. The planning pass builds wo files 
using a special internal format. These files will be used by the update puss to add "files" to the data bases. The 
planning pass also enlarges the data base files as much as necessary to accomodate the new ‘files’. ‘The update 
phase reads the plan files and adds new SAV and FIXUP ‘files’ to the data bases, If a “dircctory’ overflows, a 
new ‘directory’ is added during this pass, and all the “dircctories’ are recreated (i... all the ‘files’ have to be 
rehashed, since they were originally placed in a “directory” according to a hashing algorithm based on the 
umber of directories’). The salvage pass is used to pick up any free storage that has been lost through system 
crashes or lost through holes created during the updating of the data bases. 
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‘Throughout the entire processing of the data bases attempts arc made tw keep the data bases in a consistent 
State, ‘Directories’ are updated only after ‘files’ are guaranteed to be in the data bases. The plan files described 
are used to keep the data bases consistent in case the system crashes while the demon is in the update pass. 


A major goal in the design of the data bases is to allow recovery in case of demon errors or system disk 
crashes. fo this end the data bases ure backed up on tape every other weck. (It would be dumped more often 
but the file is currently over two million words lung). This of course leaves the problem dhat ‘files’ added to 
the data bases between dunips could be last in a disk crash, ‘To aid in recovery from such a crash, all ‘files’ 
added between dumps are copied to the "MUDRST™ directory (on I'S) or the "<MDL.SV>" directory (on 
Venex/TOPS-20). Morcover a file is kept listing all the “files added during the previous week, This file is 
called "ADDED FILES". All this information is deleted once the data base is dumped to tape. 


4.2.2. User Programs 
Occasionally i is useful for a user to list the data base ‘directories’, to see if certain ‘files’ are in it, and copy 
‘files’ out of the data base. DBMATN is a program which allows the user to do these things. 


‘The following are functions available to the user. 


4.2.2.1. Listing Functions 

CCLISTE data-base:string> 
is usod to list all the ‘files’ in a data base. It takes one optional argument which is the name of the data base 
(cither "SAV" or "FIXUP"), If no arguinent is supplied, "SAV" is used by default. (This is always the 
default whenever a function takes an optional argument specifying the dats base.) CLISTF prints cach ‘file’, 
its length, and where it is located. ‘The format ofa line of listing is as follows: 

nl fu2 size block 
where fin! is the first ‘file’ name, fin? is the second ‘file’ name, size is the length of the ‘file’ in blocks (1024, 
words for SAVs, 256. words for F IXUPS), and block is the block at which the “file” starts. This is the format 
used whenever listing ‘files’ 

<LISTF data-base:siring directories» 
is used to list all the ‘directories’ of an entire data base, It takes two optional arguments, the data-base to be 
listed. and a specification of which ‘directories to list. ‘The directories’ may be: 


a FIX; list the ‘directory’ specified by the FIX; 
A LIST of F IXs: list the ‘directories’ specified in the LIST; 


the ATOM ALL: list all the ‘directories’ (this is the default). 
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<FLIST data-bose:string> 
lists free areas of storage in the data base. It lists the free storage in the form: 

length Block i 
where Jength is the length of the area of free storage and block is the block number of the starting block. ‘This 
function takes one optional argument which is the name of the data base to be examined. At the end of the 
listing it will tell the total amount of free storage. 


4.2.2.2. Find Functions 
<FIND-FILE filessiring data-base:string> 
is used to find a specific ‘file’. It takes as its argument a ‘file’ specification and prints the “ile’ name along with 
the information printed by the listing functions if the “file” exists, otherwise it reiumns an object of type 
FALSE. The “file” specification must be of the form: 
“dirsfal fn2™ 
where diris cither SAV or FIXUP and fi! and fn2 are the first and secund “fil” namnes respectively, 
<SPEC-FIND filzssring sdata-base:siring> 
is used to find all “files” with the same basic name, disregarding the leading digit(s) which are added to make 
“file’ names unique. It takes one required argument which is the fin! to look for. It takes an optional second 
argument which is the data-base to look in. For example the call 
<SPEC-FIND "MATL"> 
‘might print: 
MAIL SAVS3 8 140 
IMAIL SAV63 8 360 


4.2.2.3. Other Functions 
DELETE filecsiring data-base:string> 
allows the user to delete a “ile from a data base. It takes the same type of "file" specification that FIND-FILE 
takes. The ‘file’ you specify will be deleted the next time the demon that maintains the data base runs. 
<GET-FILE file:siring outpulsstring dato-base:siring> 
allows the user to retrieve a “file” from the data base, It takes two arguments. ‘The first is the ‘ile’ specification, 


of the file to retrieve out of the data base and the second is the vuspur file you wish to copy it to, 
<STATUS> 


gives the information about the state of the data bases. It tclls the number of “files” and the amount of free 
storage in cach data base. STATUS takes no arguments. 
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4.2.3. Using DBMAIN 
‘There are several ways to use DBMAIN. It.can be used by typing 
2DBMAIN function arg! ...argn 
to DDT. The jcFline is of the form function arg! ... argn, where fisnction is the name of the function to be used. 
For example 
:DBMAIN FLIST "FIXUP" 
will list the free storage block for the "FIXUP™ data base. DBMAIN will kill itself after finishing and can be 
killed earlier by typing +S. 


The jet-line mentioned above can be modified to allow output to be routed to a file. This can be done by 


preceding the normal jie with » string specifying the file name of the output file. 
:DBMAIN “LISTOF SAVS" CLISTF 


will produce a listing of the files in the SAV dats base and will print this information to the file “LISTOF 
SAVS*. 


4.2.4. Garbage Collection 

One problem of the Mp. Pure-mupping Library is that many useless SAV and FIXUP ‘files’ remain as new 
revisions of user programs are created. ‘To alleviate this problem there is a garbage collection system for the 
data bases. 


‘The major goal of this scheme is to determine which “files’ in the data bases are no longer useful. To do 
this all files in the system are scanned to sce what SAV files are still pointed to (not including those pointed to 
‘only from within ITS archive files). A SAV 'file” can be pointed to from FBIN files and SAVE files. A SAVE 
file contains pointers in its PURVEC (Pure VECTOR). All FBIN files should begin with something of the form 

*<PCODE file:string> 
where file is the name of the SAV “file” associated with this FBIN. If an FBIN has more than one SAV ‘file’ 
associated with it then there can be several PCODE FORMs at the beginning of the file. For purposes of 
garbage collection, this FORM (or FORMS) must be retained whenever an FBIN file is edited. If these PCODE 
FORMs disappear, their pointers to the SAV ‘files’ will go with them, and the SAV ‘files’ might be garbage 
collected. 


‘Garbage collections proceed by looking at every file on the disk. building a list of all ‘files’ pointed to. ‘The 
Program then examines the data bases and any ‘files’ which are not pointed to are deleted. 


It is possible that deletions can fragment the free arca in the data bases. If compaction becomes necessary, 
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there exists a routine to do in-place compaction of the data bases. 


4.2,5. Internal Structure 

‘The "SAV" and "FIXUP™ data bases have similar formats. ‘The ‘files’ in the data base are pointed by 
cntries in what is essentially a hash table. Associated with each data base is a main ‘directory’ (the hash table). 
‘This ‘directory’ is located in the first 1024 words of the file. This main ‘directory’ points to other ‘directories’ 
in the data base (the hashing buckets). Fach of these ‘directories’ is 1024 words long. “The first ‘file’ name is 
used to determine which ‘dircetory’ the ‘file’ is on, ‘The structure of the main directory” is ts follows, 


word 0/ number n of entries in the main “directory” 
words I-n/ block number of cach ‘directory” 


“There can be up to 1023 ‘directories’ and cach of these can contain approximately $00 ‘files’. This provides a 
virtually unlimited ‘directory’. 


Word 0 of cach “directory” gives its length in words. From Word 1 on are ‘directory’ entries. All entries 
‘have the same two word format. ‘The first word contains the the first “file” name in SIXBIT, The second word 
contains the following fields: 


length of the ‘file’ isu blocks (a block for a SAV ‘file’ is 1024 words long while a block for a FIXUP ‘file’ is 256 
words long) (bits 1-6) 


version revision of MDL this “file” belongs to (bits 8-17) 
block in the data base where this ‘file’ starts (bits 18-35) 


‘The ‘directories’ are sorted by strict numerical order (e.g., AKA SAVS3 comes before 1AAA SAV53). 


‘Fach data base contains a free storage table. ‘This table occupies the second 1024 words of the data base. 
‘The first word of the table is the number of cniries in the free storage table. The remaining entries define 
areas of free storage. These are of the form 

length, . block 
where length is the number of blocks for this free area, and block is the block number at which it starts. 


‘There are two major differences between the *SAV* data base and the “F IXUP* data base. The first deals 
with block sizes. In the "SAV" data base the block size is 1024 words. In the "FIXUP" data base the block 
size is 256 words. This smaller size allows for more compaction of these small ‘files’. 


‘The second major difference is that while there can be many versions of the same ‘file’ in the “SAV” data 
base (c.g. NCODGE SAV53 and NCODGE SAV64), there can only be anc version in the "FIXUP" data base. 
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added. The corresponding SAV “file” for this FIXUP “file’ should 


This will be the F EXUP “file” most recently 


exist to allow the SAV file to be updated for future Mbt. revisions. 
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5. The Compiler 


pose of the MDL. compiler is to transform interpreted MDL. code into assembly language. The 


The pu 


compiler comes in several incarnations for various purposes. 


PCOMP is a program which runs the “installed” compiler ~ that is, the one which is most debugged, supported, 
d otherwise official. ‘The "P* stands for ‘purified,’ incidentally. 


NPCOMP is a program which runs a newer, less well-debugged compiler, if there is onc. NPCOMP is often 
where development work of one sort or another is being debugged. 


The "Batch Compiler.” often called Comma’, though strictly speaking the name refers w a different program 
(sce section 5.2) is a program that compiles. at night, those compilations that have been queued for it. 


The remainder of this chapter describes the specifics of interaction with the compiler, including # section on 


its internals. 


5.1. Interfacing to the Compiler 
The operation of the Mpt. compiler is controlled by a few very high-level functions and a sometimes 


les are switches and data. “his scction will describe cach such ATOM 


bewildering array of ATOMs whose val 
and its use. The reader should bear in mind that in the normal case he will be using COMMAT to set np his 


comp 1d calls, 


ions and thus will not have to deal directly with these ATOMS a 


5.1.1. Compiler Functions 
<COMPILE source:fuetion-or-ist outout:channeD> 
is the lowest level call to the compiler. It compiles exactly one FUNCTION (or a LIST of them) and prints the 
generated code on the CHANNEL given as the second argument. COMPILE is used primarily for compiler 
dcbugging. 
<PILE-COMPILE dunws:siring outout:string> 
FILE-COMPILE attempts to provide a convenient interface between the user and the compiler, “The user 


ply gives FILE-COMPILE the name of an input file, and it can do all the rest. “The user may specify other 


information about ouput files, compiler modes, etc.. but if he doesn't, reasonable assumptions are made. 


FILE-COMPILE works in the following way. First it reads in the input file and colleets inw a LIST the 


sed on which FUNCTIONS call 


ames of all of the defined FUNCTTONs that it finds. It sons this LIST ba 


which other FUNCTIONS, ‘The FUNCTIONS which call no other FUNCTIONS arc at the beginning of the 
LIST, followed by those that only call FUNCTIONs that call no other FUNCTIONS, 


dso on, Groups of 


FUNCT IONs that are mutually recursive are collected in LISTs subordinate w the main LIST. 
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Each FUNCTION will produce a separate RSUBR. COMPILE is called successively on each member of the 


LIST of FUNCTIONS. LISTS of mutually recursive FUNCT IONs arc also passed to COMPILE 


‘After cach FUNCTION oF LIST of FUNCTIONS is compiled, the resulting RSUBR is written into @ 


temporary file to enable more convenient crash recovery. ‘This file is written in such a way that, no malior 


When the system crashes, the contents of the temporary file are guaranteed to be in a consistent sta 


When all fs compiled. F TLE-COMPILE writes out an output file which is Identical to the input file except 
that ull FUNCTIONS have been replaced with their compiled counterparts. If any of the FUNCTIONS did not 
ympiler bugs, those FUNCT IONS are left unchanged in the output file 


compile due to programmer errors or 


During its operation, FILE-COMPILE mainuins a “RECORD” file which contains ull of the messages, 
Tisting of the object code 


warnings and error messiges produced by the compiler. It may aptionally produce 


produced, in MDL assembler format. ‘This is primarily useful for compiler debugging, (Note that a somewhat 


Jess complete listing may be mde at a later time. See section 7.3.) 


On IVS, FILE-COMPILE usually runs as a demon called COMBAT ZONE. In this case another interface 
called FCOMP resides above FILE-COMPILE. ‘This interface reads files that are compilation specifications 
and passes them to F ILE-COMPILE 

<FCOMP X.INCHAN juput-file ouiput-file> 
‘As most compiler usage is based on CoMnAT plan files, FCOMP is the most-scen driver of the compiler. (Note 
that the % in front of .INCHAN causes the CHANNEL the PLAN file is being read from to be passed as one 
argument to FCOMP.) 

<sTATUS> 
is an informational function; it tells how far the compilation of a given group has progressed, which 
piled. It also prints the 


FUNCTION is being worked on, and how many FUNCTIONS remain to be cor 


accumulated real time and cpu time since the beginning of the compilation. Obviously, you must *G the 


compilation to use it, but see section 8.3, 


5.1.2. Compiler Switches 


The calls to the various compiler drivers are rather short, for the simple reason that the Hing 


information is passed to the compiler as the LVALs of a set of ATOMS. 
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<SET DEBUG-COMPILE!~ bovlean> 


(by default FALSE) causes the compiler w generate extra information about what it’s doing. ‘This information 


is in the form of ‘warnings’ produced when the compiler was forced to generate less than optimal code. For 


ple, 


invocations of the arithmetic SUBRs can be open-compiled if the variables used can be determined 


be exclusively FIXes. ‘The debugging compiler will warn you if it is forced to resort tw less efficient 
arithmetic calls, 

<SET PRECOMPILED!~ file:string> 
Often, a file oF FUNCTIONS has been compiled befor 


and need to be 


. and now only a few FUNCTIONS have been updated 


sompiled-again. Most of the file is already correctly compiled: 


the entire 


ing. Ifa PRECOMPILED is given, the Mile is loaded before compilation: any functions which have 


corresponding RSUBRs in the precompilation, and which are not on the REDO Hist, are not recompiled. It is 


(© wo specify the temporary file as a precon 


lation if your previous compilation was interrupted by 


a system crash 
| <SET REDO!~ fistofaroms> 
REDO isa LIST of FUNCT ION names to be re 
pre 


npiled. regardless of whether or nut they are compiled in the 


npilation. In conj 


ation of 


tion with PRECOMPILED and PACKAGE-MODE, REDO allows comp! 


precisely those FUNCT IONs which have been changed since the last compilation, Note that COMMAT will set 
up these values more-or-less automatically in most situations. 

<SET PACKAGE-MODE!~ siring> 
This should be the name of a PACKAGE. which is assumed to be the PACKAGE being compiled. FUNCTION 
names in the REDO LIST will be looked up in the appropriate PACKAGE OBLISTs if this flag is s 


saving some typing of trailers. 


, thereby 


<SET TEMPNAME!~ file:siring> 
The compiler writes intermediate results to the temporary file, which is normally the file *sname;fum >" on 


TES, where fam is the first nam 


of the input file. It is rarely (if ever) necessary to change that default. 
| <SET SOURCE!~ file:string> 
Sou 


18 this switch causes the compiler to write out the assembler input it generates. ‘This is sometimes useful 
for compiler debugging. On I'S, such output normally goes to “snamezfinn SOURCE™, where fim is the 
first name of the input file. 

<SET SPECIAL!- bvolean> 


The compiler normally assut 


eS that variables which aren't declared SPECTAL aren't SPECIAL. ‘This means 


able only to the RSUBR in which they are declared: SPECIAL variables are bo 


that they will be avai 


ndon 


the contro! stack, just as all 


jerpreted code. If this flag is T (by default FALSE), all variables 
Will be assumed to be SPECIAL unless declared otherwise. This is analogous to SPECIAL-MODE being 
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SPECIAL, and it is not recommended that any code be written using this convention. 

<SET EXPFLOAD!~ boolean» 
If true, FLOADs in the file being compiled will be expanded at load time: what was FLOADed before will be 
treated as part of the file. EXPFLOAD is examined by GROUP-LOAD, and not the compiler itself. “The default 
is FALSE. 

<SET EXPSPLICE!~ boolean> 
{rtruc, objects of type SPLICE (primype LIST) which are encountered in the course of EVALing the forms 
processed by GROUP-LOAD will be spliced dircetly into the group: it is therefore a lot like EXPFLOAD. 
EXPSPLICE is examined:by GROUP-LOAD, and not the compiler itself. “The default is therefore FALSE. Its 
‘only known use has been to make functions at load time and have them compiled, 

<SET CAREFUL!~ boolean> 
Defaults to T. IF FALSE, the compiler will omit most of the bounds-checking code It normally generates for 
NTHs, PUTS, and so on. ‘This obviously will make the compiled code run faster, but also makes debugging the 
compiled code nearly impossible. 

<SET REASONABLE!~ boolean> 
Defaults to T. If FALSE, the compiler will generate reasonable code only if everything ever called from the 
functions being compiled is loaded into the compiler. A call to a function not loaded produces an EVAL of a 
FORM, thereby ensuring that such constructs as “CALL in the called function will work correctly. ‘This is 
admittedly pretty unreasonable (if not paranoid), whence the name of the switch. 

«SET GLUE!~ boolean> 
Defaults to T. IF FALSE, the compiler will not generate GLUE bits. As you always want GLUE bits, there is no 
reason to ever change this. 

<SET MACRO-COMPILE!- boolean> 
Defaults to FALSE. If non-FALSE. the compiler will compile MACROs into RSUBRs. This doesn’t change 
anything produced by macro expansions, but docs cause the expansion to speed up. Since the compiler 
‘expands the inacro and then compiles the expansion, this is rarcly useful. 

<SET MACRO-FLUSH!- boolean> 
Defaults to FALSE. If non-FALSE, MACROs which appear in the file being compiled will not appear in the 
resulting NBIW. ‘This saves space, at the expense of making debugging harder. 

<SET MAX-SPACE1- boolean> 
Defaults to FALSE. If non-FALSE, the compiler flushes from core most of cach RSUBR once it has been 
compiled; only the DECL is needed tw help compile other functions. Since the entire RSUBR is written out in 
the temporary file, no information is lost. “This can, for compilations which are too large, result in 
considerable improvements in speed, primarily because more space is available in the MDL. and less time is 
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spent in the garbage collector. 
<SET HAIRY-ANALYSI 
Defaults wT. If this is 


boolean> 


t set, the compiler will not perform the complex type checking it usually docs. If 
MAIRY-ANALYSTS is FALSE. the code will be generated faster, as type-analysis is expensive, but will not 


execute as Fast. 


5.2. COMBAT 
The usual method of dealing with the compiler is through the program Comnay, whose specialty is the 


preparation of ‘plan files’ to be loaded by the compiler. COMBAT is. program which knows about each of the 


previously described compiler switches and the interactions among them, It has an easy-to-use interface, an 


bility to store commonly used “p 


es! as compilation types. a 


d in general is designed w make using the 


Mp1 compiler a less-cumbersome t 


5.2.1. User interface 


Commnat’s user interface is patterned after, though not identical tw, a CALICO int 


e[1}. In particular, it 


‘capects in response to any given prompt a particular ype of input from the user. which may be a file name, a 


‘symbol’, of text. Ordinarily, the type of input expected is indicated by the “syntactic prompt’ which follows 
the normal prompt: this is one of “( FILESPECY’, "( SYM)’, and “(TEXT)'. ‘The “Toggle verbosity* compilation 


type turns the printing of the syntactic prompt on and off, and causes a tailor file to be written out when used. 


A 


umber of special characters are defined for any of these types of input 
+@: Clears the input buffer, as in MDL. 
1D: Redisplays the input buffer, as in MDL 


tL: Clears the screen and redisplays the input buffer, asin MDL. 


*G: When given as the first character of an answer, allows one to get the answer from a user-defined type. 
See the section on tailoring. 


7Q: Has special effects when a compilation plan is being made (sce below), 
Input. 


jcc also the section on file name 


FR: Causes COMBAT ta “back up’. Typically this means go to the previous question asked, but in certain 
modes it may have a slightly different effect. When a MUBCOM Is running, this kills it and backs up to the 
last question asked. 


1S: Abnormally ends whatever is being done, and returns to the “Type of compilation’ question. If a 
Mubcom is running, it will be killed. When a long compilation plan (‘How to run’ is ‘Many') is being 
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made, the portions already made will be saved. Sce the “Flush many" compilation type. 


2: When given as the first character of an answer. this causes a more detailed description of what is expected 
to be printed, along with the current default and how to obtain it. 


As ‘This quotes whatever character follows it, including DEL, ESC, ete. It does nor have the effect of quoting 
range characters in file names: sce the section on file name inpul. \, used as a quote character, never 
\d cannot be rubbed out. 


In addition, when the syntai 


prompt is (SYM), +F is useful (sce below). 


6.2.1.1. Symbolic input 
If you are funitiar with CALICO, this scction can probably be skipped. When entering symbolic input, 


squired to uniquely specify the desired choice: the interface will complete 


‘one need only type the characters 


the response, and in addition can display the available choices at any point 


SPACE completes the response as far as it can. Ifthe response is uniquely specified, it will be displayed in 


its entirety. followed by “1°; if more than one choice is still pussible, then the portion of those choices which is. 
id "Expand 
be displayed if the "Ex 


tinambiguously specified will be displayed, followed by “&*. For instance, if Expand fluads’ a 


splices’ are among the choices, and “Ex SPACE” has been typed. “Expand & w 


reduces the choices to those two. 


In some cases, if SPACE is the first character typed, it will select the default (first) choice and terminate, 
When +F is typed, all remaining choices will be displayed. 


‘To terminate responses 


this mode. cither ESC or CRLF may be used. In cither case. the current 
response is completed as far as it can be. If only one choice then remains, the answer is terminated and the 


single choice will be used. If more than one choice is possible, it is just as if SPACE had been typed. 


Typing ESC of CRLF before any other characters have been entered causes the default answer to be used. 


5.2.1.2. Filenames 


File names lard dev: sname:fuame! frame? format on ITS; on Tenex/TOPS-20, 


re expected in the sta 


standard file name recognition is used. ‘Typically, typing simply ESC or CRLF answers ‘no tw the question, 
while SPACE ESC says ‘use the default’. In certain special cases ("Input file” and “Output file"), when some 


answer to the question is imperativ default will be used in either case. File names should not be 


surrounded by quotes in this mode; they are not MDL STRINGS! 
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tis rather painful to get funny characters (such as SPACE) into file names. When the file-name parser 
| S008. 70. it uses the following character in the name being generated regardless. Unfortunately, the *@ must 

be quoted to get it past the reader. since it has special effects in the normal case. ‘Thus, the file name given to 
MDI as “TAA; FOO >” hasto be wyped to COMMAT as TAA: \7. FOO >. 


5.2.1.3. Text 


| Text is just that: relavively arbitrary ch 


acters, terminated by ESC. Since CRLF is allowed in text, it does 


not terminate input. ‘Text type input is used in a number of cases where it 


quite appropriate, such as the 
"Redo list’ and "Packag 


jode™ questions. If it is known that the expected response is. a LIST of STRING, as 


those cases, the appropriate brackets or quotes should Hur be typed. 


5.2.2. Combat Questions 
This section discusses the questions that can be asked of the user during the preparation of a CoMna't plan 
file, which is FLOADed by the Comma demon or by PCOMP to effect a compile 


a. ‘The perceptive reader 


strong resemblan 


to section 5.1.2, in which the switches relevant to the compiler are listed. 


Questie 


asked by the pre-existing compilation types (’Verbose’ and “Short’) are so indicated. Al questions 


| ire available in user-defined compilation types (see section 5.2.5). 


“Sname’: sets the default directory for questions that want a file name as an answer: also causes the FORM 
<SNAME sname>. where sname is the answer given, to be included in the plan. ‘This sets the default 
directory for files referenced by the compiler; it also causes the temporary file (see below) to go to the 
sname directory. 


Often. when there is anly one compiler, this question will not be asked. If answered 
alfirmatively, it causes the FORM 


<OR <GASSIGNED? EXPERIMENTAL!-> <NEWCOMP!->> 
to be included in the plan. ‘This FORM will load a new compiler on top of the old if necessary. 
“Debugging compiler? (Verbose): causes DEBUG-COMPILE ! ~ to be set to T. which causes the new compiler 


( generate extra information about what it's doing. This currently is asked only if the new-compiler 
question is answered affirmatively. 


“Input from” (Verbose and Short): the file to be compiled. This appears in two places in the plan: as 
<SETG COMBAT!- input-file> 
1110 FCOMP described below. 


d in the 


O 


put to" (Verbose): the file name to be used for the NBIN. The default is the input file name, with NBIN as 
the second file name instead of whatever it was for the input. ‘This completes the call to FCOMP that ends 
every plan: 


$2 comBaT. 


| 


—— 
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<FCOMP %.INCHAN input-file output-file> 
“This call is what actually Invokes the compiler. 


“Precompilation from’ (Verbose): specifies a file containing a previously compiled version of the input file. 
‘Any FUNCTIONS which have corresponding RSUBRs in the precompilation. and which are not on the 
‘Redo list, are not recompiled. It is appropriate to specify the temporary file as a precompilation if your 
previous compilation was interrupted by a system crash. Scts PRECOMPTLED! ~ 


“Compare with’ (Verbose): ‘This question is asked only if'a precompilation file is specified. If answered 
‘affirmatively (user types either SPACE ESC or a file name) MULCOM (sce section 8.1) will be run with jet 
Of the input fle name. and the file name provided here (the default is as for precompitation), plus some 
extra stuff specified below, If FOO NBIN" is given here, then MUBCOM will look for the newest revision 
‘of FOO which was created befire the NBIN, MUPCOM determines which FUNCTIONS in the fite have 
Changed und therefore need ty be recompiled. It also determines whether the file Is a PACKAGE, and 
lnwers the "Package mode” question appropriately. IC is therefore not usually necessary for the user to 
answer the Redo’ and ‘Package mode’ questions dircetly, 


“Check macros?" (Verbose): asked only ifCompare with’ is answered affirmatively. “Tis adds */M" to the jel 
passed to MUDCOM, which causes it to check for MACTOs and MANIFESTS which have changed: if a 
FUNCTION wiscs a MACRO or MANIFEST which has changed, the FUNCTION will be listed as changed. 
Mupcom does not normatly check for this. 


“Extra ICL (Verbose): asked only if Compare with" is answered affirmatively. Whatever is supplied here will 
be passed to MUDCUM as fel, before the files to compare. ‘This can be used to load macro files: see section 
Bl. 


“Redo’ (Verbose): asked only if'a precompilation file was given. Takes a bunch of FUNCTION names, which 
‘Will be recompiled. Note that the names supplied here will be appended to the fist returned by MURCOM, 
ifany, and that duplications in the list are ignored. Sets REDO! 


“Package mode’ (Verbose): asked if'a precompilation file was given and MUDCOM was not nin (MUDCOM will 
set this if run). ‘This should be the name of a PACKAGE, which is assumed to be the PACKAGE being 
compiled. FUNCT TON names in the “Redo’ list will be looked up in the appropriate PACKAGE OBLISTs if 
this flag is set, thereby saving some typing of trailers. Sets PACKAGE -MODE !~. 


“Temporary file to 


rhe compiler writes intermediate results to the temporary Mile, which is normally 
*suame;fuamel >" (on ITS) 
"<name> :faame.TEMP™ (on'Tenex/TOPS-20) 


You may change that by answering this question; there is rarely a good reason to do so, Sets 
TEMPNAME !~. 


“Source file to": “The compiler can be caused to write out the assembler input it generates by answering this 
question, Assembler output normally goes to 
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Mamel SOURCE™ (on ITS) 
"Gsnae> ; name. SOURCE™ (on Tenex/TOPS-20) 


which is the default for this question; another name may be prwvided if desired. Scts SOURCE ! ~ 


Special?’: "The compiler normally assumes that variables which aren't DECLed SPECTAL aren't SPECTAL. If 
Unis flag is T (defaults to FALSE), all variables will be assumed to be SPECTAL unless declared utherwise. 
Sets SPECIAL! ~ 


Expand Moads?: (Verbose) If truc, FLOADS in the file being « 
EXPF LOAD! - 


npiled will be expanded at load time. Sets 


Expand splices?': If true, objects of type SPLICE (PRIMTYPE LIST) will be expanded and inserted into the 
group. Sets EXPSPL IC 


‘Curcful?": (Verbose) Ry default T. but if FALSE. the compiler will omit most of the bounds-checking code it 
‘nurmually generates fir NTHs, n Faster: it 
also makes debugging the compiled code nearly impossible. Sets CAREFUL! — 


PUTS, and sv on. This obviously will make the compiled code 


Reasonable”: By defwilt T. but if FALSE. the compiler will generate reasonable code only if everyth 
call from the functions being compiled is loaded into the compiler. Sets REASONABLE ! ~ 


Gluc?: Hy default T, but if FALSE, the compiler will not generate GLUE bits, “There is no good reason to 
ever answer this. Sets GLUE I~ 


‘Macro compile?: fy default FALSE, but if truc, the compiler will compile MACROs. Sets 
MACRO-COMPILE | ~ 


“Macro flush?': By default FALSE. but if truc, MACROs which appear in the file being compiled will not 
appear in the NBIN. Sets MACRO-FLUSH! 


Max space? By default FALSE, but if true. the compiler flushes from core most of each RSUBR once it has 
been compiled: only the DECL is nceded to help compile other functions. "This can, for compilations, 
which are very large. result in considerable improvements in speed. Sets MAX-SPACE ! 


“First things to do’, “Uhings to do’ (Verbose), and “Last things to do’: It frequently is necessary to perform 
some actions before a compilation can be run: definitions files must be loaded, special environment setup 
might have to be performed, and so on. Ail three of these questions are designed to allow that: whatever 
you supply is put out after everything else in the plan but before the call to FCOMP, ‘There are three 
questions, instcad of onc. to allow some things tw be specified in a tailored compilation type, while others 
are provided at compile time, or possibly from another tailored type. ‘The three questions do not depend 

on each other; they are asked in the order given here, and the answers appear in the plan in the same 

order. 


5.2.3. Requesting Compilations 


The first question asked by CoMnaT is “Type of compilation’. In addition to a number of special 


Possibilities described later, there are two answers to this question (in addition to any provided by the user 
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through the tailoring facility) which request pre-defined tailored compilation types. These are ‘Verbose’ and 
‘Short’. 


"Verbose’ causes all the normal questions to be asked: “New compiler? ‘Input file’, *Precompilation’, 


thes, “Mhings to do’, and so on, ‘Short’, on the other hand, det 


Its the answers to all questions except 


‘New compiler?’, ‘Input file’, and "How to run’. 


When requesting a compila offect as an 


jon, one may type 7 at any time. ‘This has the same immed 


ESC, but in addition causes all questions between the one just answered and the “Things to do’ question to be 


defaulted. ‘This is particularly uscful in the "Verbose" sequence of questions. 


If’ Many" was give 


is “How to nun’ for a previous compilation request. and the resulting plin has not yet 


been written out, subsequent plans will be appended to 


i. Using “Many” will sometimes effect a major 
savings of time if several compilations wish to perform the same environmental setup: f'they USE many of 


the same PACKAGES, for example, When using ‘Many’ in combination with predefined compilation types, it 


is useful to remember that whatever is specified under “Things to do" may end up being performed for cach 


plan. You might modify your compilation types to reflect this, oF alternatively, edit the plun file produced by 


Comnar to remove redundant operations. 


The only way to get rid of the ‘Many’ plan is to answer ‘Many flush’ w the “Type" question. Typing +S or 
answering ‘Abort’ to the "How to run’ question will abort the current portion of the "Many" compilation, but 


not the whole thing. 


If "Many’ was mistakenly given as ‘How to run’, and you don’t wish to destroy the plan you have 
generated, it is possible to (in essence) go back to the “How to run” question by answering ‘Many print’ for the 


compilation type. In this case, you are no! back in the plan-making loop; 7R acts just like +S. 


‘FR, here, backs up to the last question asked. ‘There are two qualifications. First, if 1@ has been typed, 


then it backs up to the last question that would have been asked if +Q had not been typed. Second, the four 


questions “Precompilation’, “Compare’, *Redo’, and ‘Package mode’ are treated as a group: if the “Package 


mode’ que 


jon has not yet been answered, it is possible to back up normally; but once that question has been 


answered, backing up to it will go to the first member of the group, ‘recompilation’. 


7G allows one t obtain the answer to the current question from any user-defined compilation type. It 


requests a type 


1d uses the answer or default supplicd therein, printing the information so obtained. 


The +6 must be typed as the first character of the answer for this to occur. 


lows one to use parts of a 


COMBAT $2 


The MIDI. Programming Environment 89 


defined type without either using the type itself or altering it for the occasion. For “Text’ type input (such as 
Things w do’), the string is placed in the input buffer but not completed, so it may be edited before an ESC is 


typed, Sce also the "Xerox type" command. 


Note that there is a distinction made between ‘Compare’ and *Redo’; the former causes a MURCOM to be 


in, and the latter asks for the names of FUNCTIONS to be recompiled. 11 is possible to do both, in which case 


the two groups of FUNCT IONs are appended to form the ‘Redo’ list for the compilation, Note also that if a 


MUDCOM has been run, the “Package mode" question will not be asked, since the answer is supplied by the 


Mubcom, Hither +R or #S may be used 


kill a running MupcoM. 


One of the responses to the "1 


Wt FUN” question is “Abort, which returns dircetly W the “Type of 


pilation’ question without writing out 


plan, starting up 


PCOMP, or anything else, Its effect Is exactly 


of a tS. In pat 


icular, if you are making a long plan, only the portion just completed, nor the entire 


mpilation, will be aborted, 


also possible at the “How to run’ question to supply an answer to any of the compilation questions 


(nput file, ete.). “The ‘Question’ response asks for the name of a question, then asks th: 


question. Any 


number of questions can be asked in this manner, one at a time. “This Is particularly useful for filling in the 


blanks left by a “Short’ type compilation, or by user-defined compilation types. 


Whew a compilation request has been finished, Comat nonnally loops back to the “Type of compilation’ 
question, but changes the default from *Verbose’ to "None" (meaning ‘Quit’, unless another compilation may 


reasonably be expected. ‘Thus, one may leave by typing a single ESC. 


It is possible to modify Comuat’s behavior such that it cither kills itself after Finishing the compilation 


plan, or loops back with "Verbose" us the default for the “Type of compilation’ question. 


i then examines the current compilation type: if “Another compi 


question will be asked with default "Verbose’; if it has been set to ‘No’, COMBAT will Kill itself; if to "Ask’, 


further consideration is required. 


with the "Verbose" defiult. Otherwise, COMBAT examines the state of two tailorable switches, 


« by the 
| “Another compilation?’ compilation type, If Another compilation?’ has been set to "No", COMNAT will die; If 


‘Yes’, the type question will be ask: 


default *Verbose’: if to "Ask", the type question will be asked 
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with default ‘None’. Normally this is ‘Ask’ 


Note that “Another compilation? is like “Toggle verbosity” in that it will have no effect unless user-defined 


compilation types exist. 


5.2.4. 'How to Run’ Options 


here are four options available when answering the “How t Run’ question which determine where your 


plan file will be written and when the compilation it specifies will be run, 


‘Pcomp’ places the plan file on the CSNAME> directory. and names it "PCOMP >". Additionally, COMBAT 
start a PCOMP (ar NPCOMP, as appropriate) process if itis exited after writing » PCOMP file. “Peomp' is 
pilation in one’s own process, 


the standard method for running a6 


‘COMIAT® Writes the plan file Ws “COMBAT; PLAN >". ‘The COMMA demon successively compiles all such 
plans at night. informing the persons who submitted them of the result. 


‘Was to" is like “COMMAT’, except that the plan is written to “COMBAT ; WASTE >". ‘The ‘waste™ queue is only 
run after midnight, which is usually sufficient for thos ons, "Waste 
is the answer used by default for "How to Run 


wh are doing ‘overnight compil: 


F 4 Te" places the plan file on the <SNAME> directory, and names it "PLAN. >". “This means that it will not 
be run until you explicitly load it into a compiler process. 


5.2.5. User Tailoring 
Itis often the case that a particular file is compiled quite often, or that some sequence of actions must be 


performed as the “Mhings to do’ before many compilations. CoMnar allows the user to define his own 


‘Compitation types’, each of which specifies exactly those questions which should be asked and the answers 


for those which should not. For example, one could have a ty 


ign’. which says that the input file 
is always “SEND;ESIGN >" and in addition provides for the FLOADing of two files in “Things to do’. 
Further, since most questions are defaulted, one might choose w answer only these questions which are 
interesting, such as Precompilation’. It is also possible to supply a default answer for a question which will be 


asked. 


In addition, there are some questions which are not asked by the “Verbosc’ compilation type, but which 
evertheless are available t user-defined types. ‘These are: "Macro compile’, ‘Macro flush’, 
and others. 


“Expand splices’, “Special mode’. "Glu 


One can select any of one’s own defined compilation types as an answer to the “Type of compil 


types are 


ion’ 


cm hort’. Except that the questions asked may differ, user-defined 


estion, just like “Verbose” and “S 
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identical to the predefined types. 


5.2.5.1. Tailor files 
User-defined types are saved (and loaded) from the file "same: %COMBT TATLOR™. It is possible to load 
other tailor files, but the "ZCOMBT™ file in. sna 


is loaded during startup, ‘Tailor files are quite similar to 
Mp1. GC-OUMPed Mites and thus cannot be edited other than with CoMmAT. 


5.2.5.2. Create type 


This special compita 


YPC requests a name for the type being made, then enters a loop with the prompt 


‘Question’. One may choose 


ny of the available questions, and cither supply an answer or (by default) 


request that the question be asked when a compilation of this type is being submitied. Note that only the 


How (0 run’ and the following “Type of © 


pilation?’ questions will be asked unless others are explicitly 


supplied; but one may supply answers to “How to run’ when creating a type. 


nde, +R will return to the “Question” loop if one is about to supply an answer: otherwise, 


it returns 
t the “ype of compilation’ lwop, aborting the type creation. 


7G behaves exactly as it does in the normal loop. To indicate that one is finished, one should answer 
to the Qu 
question: the last one given will be used. One may wish t default a particu 


tion’ prompt. It is possible co supply several different versions of the answer to a particular 


lar question. after specifying that 
Ic was to be asked or after supplying some different default. ‘This may be done by answering ‘Delete question’ 
tw the ‘Question’ prompt, whereupon one will be asked for a particular question to ignore. ‘This question will 
then be completely ignored. Note that all interesting questions are initially in this state 


‘There is also a “Set question default” ‘Question’. This requests a question name, then asks the user to 
Supply an answer. ‘The question will be asked, with the default supplied. ‘Thus default settings of switches can 


be changed, and one can supply a file name for the precor 


jlation while still being asked whether 


precompilation is desi 


Unfortunately. ¢ 


er-supplied defaults for “Text™type questions are used if ESC is 
nswered: to get rid of the default, type SPACE ESC. Note that 


is is exactly the inverse of the convention 
for defaulting file names. 


When ‘Finis’ has been typed, 
Load ta 


new copy of one’s 


lor file is written out. ‘This may, in combination with 


lor’ and ‘Replace tailor’, have undesirable side effects. 
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5.2.5.3. Print type 
This requests the name of one of the types currently loaded, and prints out for it all questions which cither 


will be asked when a compilation is being submitted or which have user-supplicd defaults, If a particular 


question has been globally “turned off (such as the "New compiler? question, when there is no new compiler), 


an asterisk will be printed on the appropriate line to indicate that the information there is currently not used, 


5.2.5.4. Delete type 


fone of the currently-loaded types, and deletes it. A new copy of the tailor file is 


This requests the nam 


written out. so all trace 


Fthe type will vanish when this command is used, 


5.2.5.5. Alter type 


This requests a type name, then becomes identical to “Create type’, except that se 


ne questions already 


have answers, Again, “Kinis' must be typed to leave the loop and cause the modifications w be filed: typing 


+R or +5 will leave the 


p. but the modifications will be forgotten. 


5.2.5.6. Load tailor, Replace tailor 


Both of these request a file name, defaulting to the last one used for cither a “Toad 


lor’ oF ‘Replace tailor’ 


command. Initially this is “siame;COMBT TAILOR. ‘load tailor’ appends the types defined in the 


specified file to those already loaded. whi 


Replace tailor first throws away those already loaded. ‘The types 


defined in this way are not distinguished frum those loaded from one’s own CoMAr tailor file: in particular, 


ate’. "Alter", and “Delete type" will eause all the types currently leaded to 


using “Toggle verbosity’ or any of 
be written out to the CoMnaT tailor file. If, therefore, one has done a “Replace tailor’, one can casily lose all 


of one’s own types in this manner. L.c., itis very casy to destroy yourself, 


5.2.5.7. Xerox tailor 


This requests the name of an existing user-defin 


sd type, and a new type name. ‘The new type becomes an 
exact copy of the previvusly-cxisting type. This is particularly useful when one has several different types 


which do almost the same thing. 


5.3. The Compiler (internals) 
The compiler's job Is | tke a Mbt FUNCTION or group of FUNCTIONS and produce an operationally 


equivalent machine-language subroutine (RSUBR) using whatever information can be extracted from the 


swurce code and whatever additional information the user wishes to supply. “Ihe efficiency of the output code 


produced is directly proportional to the amount of information supplicd by the programmer and inversely 
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proportional to the generality of the source program. 


the information supplied by the programmer is usually in Uhe form of optional data-type declarations 


(DECLS) 


nd the use of programmer-defined data types (NEWTYPEs) that have built-in declarations, Unlike 


many programming languages. however, declarations are never required. ‘The compiler w 


programs with no deel 


Jons at all, but the resulting output will not run as fast as with well-declared code. 


The current compiler can achieve speed-up factors of anywhere from about 4 to 100. The factor of 4 


nts the speed-up for a very general progra 


tions. On the other hand, th 


n with very poor dec 


factor 


of 100 represents a program with a very narrow range of 


plication that has very good (that is, restrictive) 


declarations. ‘Typical progeamns can expect tw achieve factors of 20-40. 


5.3.1. How it Works 
The compiler as it currently exists is really two distinct programs. GETORDER is basically an interface 


between fil 


Sof MDI functions and the compiler. It is a relatively small program that reads in the file, sets u 


ind writes out the final file oF RSUBRs, 


the various compiler switches, calls the compiler one or more times 2 


COMPILE itsclf is basically a compiler with three major snd thi 


minor passes. Pass 1 builds a model of 
the program, pass 2 analyzes each node of the tree and docs data type analysis, pass 2.5 (minor) allocates stack 
space for variables and temporaries, pass 3 generates output code and two minor passes do final stack 


allo 


ation and peep-hole optimization. 


5.3.1.1. COMPILE and COMPILE-GROUP 


There are two distinct modes of compilation ay 


lable. ‘They are simple and multiple. Simple compilation 
‘occurs when COMPILE is called with one FUNCTION. It simply compiles that FUNCTION and returns, 
Multiple compilation occurs when COMPILE is called with a list of FUNCTIONS. It compiles cach FUNCTION 
into a separate RSUBR. It differs from multiple calls to COMPILE in that it sometimes partially compiles a 


t of order to determine its calling sequence and do argument type-checking. ‘This behavior is 


necessary when compiling mutually recursive FUNCTIONS. 


In all modes of compilation, COMPILE-FUNCTION Js called to actually compile the individual 
FUNCT IONs. It calls the various compiler passes. 
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5.3.2. Modeling Pass 

The first pass of the compiler takes the input FUNCTION and builds an expanded model of it. In the 
process uf doing this, it produces a symbol table entry for every local variable bound and/or declared in the 
FUNCTION. any of its PROGS/REPEATs or MAPF/MAPR FUNCTIONS. It also produces the RSUBR DECL for 
1 is, an entry which can be called efMiciently 


the final output. Pass 1 also tries to decide if an internal entry (th 


Gee section 6.1)) can be used with this FUNCTION. If an internal entry turns out te be possible, Pass 1 


generates an appropriate calling sequence for internal calls to use. 


Nhe model built by Pass 1 looks like the original FUNCTION with all of the nodes in the FUNCTION'S 


structure replaced with objects of type MODE (a new type defined for the compiler). A node in the model may 


have anywhere from $ t 30 clements, ‘The 5 clement node is for simple qu injects like fixed-point 


numbers, ATOMS ctc. “The 30 clement nodes are for major elements of the program such as the node for the 


FUNCTION itself and nodes for PROGs and REPEATS. ‘The majority of the nodes are general SUBR nodes, 


which have 10 cements. 


The Pass 1 structure is built in the following way. The top level program in Pass 1 generates a node for the 


entire FUNCTION. ‘This node gets the following information put into it 


1. A code specifying that this is a FUNCTION node 
2. The data type that this FUNCT TON is declared to return (or ANY). 

3. A LIST that will eventually contain the nodes comprising the body of the FUNCTION. 
4. AUVECTOR of internal names for internal calls to this FUNCTION. 

5. A symbol table for the variables declared and/or bound in this FUNCT ION. 


6.A list of entries in the symbol table specifying how the arguments are to be set up (whether they 
are optional, QUOTEd, TUPLE etc.). 


7."The final RSUBR DECLs. 


A specification of how to pass arguments ts this FUNCTION when it is compiled (whether the 
arguments should be in registers or on the stack), 


9. The number of required arguments and the total number of possible arguments. 


In addition to the above information, slots exist in the node for additional informa 


jon to be supplied by 


tater compiler passes. 
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After the main node for the FUNCTION is built, the sub-nodes for the FORMs comprising the body of the 


FUNCTION are built. This is done by first dispatching to special Pass | code for the first clement of the FORM. 


Ifno special code exists for this first clement, a dispatch is made on the TYPE of the first clement of the FORM 


(that is, ATOM, FIX, FUNCTION ctc.). If no special code exists for cither the first clement or its TYPE 


general FORM node is built. Tn the case of an ATOM as the first clement of the FORM, the normal lookup rules 
are invoked on the ATOM and it is dispatched again based on its valuc. ATOMS with no values cither cause 


compilation warnings or are assumed to be RSUBRs (depending on compiler switch REASONABLE). 


All FSUBRs (COND, AND, OR, FUNCTION, PROG, REPEAT, UNWIND, cic.) have special Pass 1 code and 


produce very specific nodes. Most SUBRs don't dispatch to specific code during this pass, ‘The exceptions are 


things like MAPF, ILIST, GET cle. which have somewhat non-stuundard treatinent of the 


arguments. 


(Actually, MAPF and MAPR don’t tr Pass 1 


at their arg andardly, but they are treated spectally in 


so that the inner FUNCT TON may be open compiled.) 


As mentioned previously, all nodes have att least $ elements. ‘These are as follows 


1. A node type code. 


2. A pointer to the parent node (if one exists) 
3. A specification of the data type the node will generate. 

4. A list of sub-nodes referred to as kids. 

t nodes. 


5. A name for the node, which may have different meanings for differe 


In addition, nodes other than nodes for QUOTEd objects have additional elements that are filled in during 


later passes of the compiler. 


After Pass 1 all additional passes work on the model built during Pass 1. ‘The original FUNCTION is no 


longer even considered. 


5.3.3. Analysis Pass 
During Pass 1, very little information is determined regarding the resulting data types of various nodes. 
Indeed, with the exception of nodes produced by quoted objects, structured objects which will produce code 


tw build copies of the 


selves, and FUNCTIONS, PROGs and REPEATS with declared values, no type 
information is produced. ven in the cases where type information is produced during Pass 1, it is usually not 


ing 


33 ‘The Compiler (Internals) 


| as detailed as other passes would like. ‘The Analysis Pass has the job of ult type of cach 


96 he MIDI Programming Environment 


individuat node based on various criteria 


1. The declared types of the variables.used in the program including GDECLs and MANIFESTS 


2." me known type transformations produced by various SUBRS. (For example, it is known that 
LENGTH always produces a F IX result.) 


5, Some anilysis of the context of the nodes within we prograre. (For example in the following 
code: 
<COND (<AND CTYPE? .X LIST> <NOT <EMPTY? .X>>> 
<1 .x>)> 


scpardless of how X is declared. itis obviously a LIST when the EMPTY? is nun. and it obviously & 


hot empty when the <2. .X> isan.) 


she Analysis Pass performs a standard depth-first Yef-torright tree walk on the Pass V model, “The male 


« an initial dispatch based on the node type of each 


dispatch function during this pass is called ANA. It d 


node, Since most nodes are sll considered “SUBR nodes’. most of the dispatches end up ot the suse call 


snatyrer. “The SUBR call analyzer has wo types of further dispatch available. ist it looks if 8 table for 


‘SUBRS that arc capable of bein; spen-coded: if it finds an entry in the table, the analyzer for that 


SUBR is invoked. IFthis SUBR Is incapable of being open-coded, ANA checks another tbe $66 if this SUBR 
has an internat entry available. Iit does. the node is changed from a SUBR nade co an internal SUBR node. If 
both dispatches fai, another table is checked to sce ifthe object type retumed by this SUBR is known, and ifit 


is the result is put into the SUBR node. 


Most of the work done by the Analysis Pass happens when the first dispatch occurs and specist sUBR 


analyzers are invoked. Generally speaking. these analyzers check to soe if they Know enous about their 


tion. For example, an invocation of the SUBR 


arguments to transform their nodes to an open-code specifi 
REST only transforms to an open-code node if both the PRIMTYPE of the First argument is known at compile 
ime and there are no SEGMENTS in the call to REST, If a special SUBR analyzer decices that it can't 


open-compile in this case, it either leaves the node asa SUBR nade or transforms it 10 a0 internal SUBR node. 


5.3.4. The Type Analysis Model 


Th addition wo the model of the FUNCTION built in Pass 1, the Analysis Pass adds additional information to 


tne model concerning the current states of local variables. As the anatyrcr plunges down into the tres, it ties 


‘ble. Specifically, there is a slot in each symbol table entry 


to keep track of the current DECL of each vari 


called CURRENT-TYPE. The analyzer updates that slot based on its current knowledge, / call to SEY causes 


the CURRENT-TYPE slot Jnanged to the analyzed type of SET's second argument. When multiple 


“The Compiler (Internals) 33 


— 


a 
SEE 
er 
ee 
ee 
ee 
ee 
er 
9 
—————————————————————— 
a 
SS 
rr 
——————————— 
er 
9S 


The MDI. Programming Environment 97 


control paths meet, the CURRENT-TYPE slots of a variable arc OR’d together at the joining point. 


Conditions 


contro! structure nodes for COND, AND and OR also maintain two lists of transient information: 
These 


‘at information will be valid if the true or false 


called TRUTH and UNTRUTH. They specify w 


branches are U 


en respectively. For instance, a COND clause compilation can assume that any TRUTH 


Information generated in the predicate of the COND will be valid for the rest of the clause. 


Some of the analyzers for the more widely used predicates have special code in them to add information to 


the current TRUTH and UNTRUTH values. ‘These predicates include TYPE?. EMPTY?, LENGTH? and NOT 


Looping control structures pose additional problems for the type anal 


is model. ‘The approach taken by 


the type analyzer is to bi 


Id a copy of the current types of all varlubles before analyzing the loop structure. 


This copy of the local ype information constitutes the assumptions currently in effect. After the loop analysis 


is compete, the assumptions are checked against the current state of the variables. If any of the assumptions 


have been violate 


d, the assumptions are updated and the loop is re-analyzed. 


5.3.5. 


The Analysis Pass also performs a life-and-death 


je-and-Death Analysis 


alysis on the Jocal variables. ‘This is done by assuming 
that the variable’s value is dead at each LVAL node for that variable. Ifanother LVAL node for this variable is 
discovered that is reachable from this one before any intervening SET nodes for this variable, the original 


node is updated to be alive. ‘This life-and-death information is used during the Code Generation Pass. 


5.3.6. The Variable Allocation Pass 
‘The Variable Allocation Pass (VAP) is a relatively simple one. Its purpose is to allocate stack space for all 
of the variables bound in the FUNCTION, its PROGs and REPEATS and its MAPF /MAPR FUNCTIONs. There 


are various switches that control the manner in which this allocation is performed. 


The mo 


important switch specifies whether or not this FUNCTION needs a FRAME or not. ‘The VAP 
always starts out assuming it does not need to build a FRAME. This assumption will be changed if it is 


discovered that extertially accessible named ACTIVATIONs cxist in the FUNCTION or any of its inner blocks 


(PROGs or REPEATS or FUNCT IONs) or if at any time it is discovered that the address of a variable cannot be 


1d a5 a fixed offset from the top of the stack. Whenever this assumption is changed, the VAP siarts 


over again with the new assumption in affect. 


Another switch that controls the behavior of the VAP specifics whether or not the stack slots for inner 
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blocks will be pre-allocated because the stack will be in a "fuzzy" state when these blocks are running. The 
stack is Said to be in a “fuzzy” state when the number of slots currently being used cannot be determined at | 
compile time. ‘This usually occurs when a TUPLE is being constructed fora MAPF. For instance, in | 


<DEFINE F (XZ) 
MAPF .VECTOR <FUNCTION (Y) < 


2 .¥ 2222 .X>> | 
the elements of the VECTOR will be between the top of the stack and the location of variable 2, Even if F has | 


4 FRAME, the location of ¥ will not be known relative to the FRAME pointer at compile time. “Therefore, the 


Initialization code for F will pre-allocate the stack space for Y. 


Du 


g the VAP, each symbol table entry gets its address field set based on where that variable will be on 


the stick, Also nodes for PROGS, REPEATs and MAPF/MAPR FUNCTIONS that have bound variables get 


Judes where the SPECIAL variables start 


additional information inserted in themselves. ‘This information is 


and where the UNSPECIAL variables start. 


5.3.7. The Code Generation Pass } 


The Code Generation Pass (CGP) is probably the most complicated of all the passes. Fortunately, the 


Analysis Pass has already refined the model so that the CGP can dispatch immediately to the special-purpose 


code generators. Resides building a list of assembly-language instructions as output. the CGP keeps track of 
the current state of the stack, the contents of the registers, the current state of variables (whether they are in 


registers or on the stack or both) and the contents of the temporaries. 


The gencrat dispatch routine during the CGP is called GEM. It takes two arguments: A NODE and a 
specification of where to leave the result. ‘The second argument’can be any of the following: 


L.'The ATOM FLUSHED, meaning that the code will be executed for effect rather than value, 


2.'The ATOM DONT-CARE, meaning that the caller of GEN is Icaving the decision up to the specific 
generator as to where to Ieave the result. 


3. An object uf type DATUM which specifies a place for the type and value of the result to be left. 


Type DATUM is of PRIMTYPE LIST and contains two clements, onc for the type and the other for the 


value, The elements of a DATUM may take on a Variety of valucs in different circumstances. ‘These include: 


1.A TYPE name. This can only occur in the type slot and it means that the type of the object is 
known at compile time and this is it. It indicates that the code generator need not put the 
lype-code anywhere. 


2,'The ATOM DONT-CARE. ‘This means that the caller doesn’t care where the result for this field is 
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3. The ATOM ANY-AC. This tells the generator to leave the result in any a\ 


ailable AC. 
An object of type AC. ‘This tells the generator to force the result into a specific AC. 


5. An object of type ADDRESS: C or ADDRESS: PAIR. Both of these specify addresses on the stack 
or in the interpreter. 


6. An object of type OFFPTR. An OFFPTR has three ficlds: 2 DATUM, an offset (a FIX), and a 
PRIMTYPE. An OF FPTR tells the generator to lei 
DATUM and offset by the offset 


in the word pointed to by the inner 


1fun clement of a DATUM is ANY~AC oF DONT-CARE, the generator is required t update the DATUM to 


reflect the actual location of the result. Ifthe clement is a TYPE, the generator may change it to an AC which 


happened to end up with the TYPE in that AC. 


The generators always return a DATUM spe 


ying where the result was actually left, unless the caller 


ied the result FLUSHED. ‘There is one special DATUM that can be re 


ned. It is the GVAL of the ATOM 
NO-DATUM and it means that the specified node will not return a value (that is, it isa RETURN or an AGAIN or 
jething). 


The! 


are six objects of type AC in the compiler, corresponding to ACs 0, A, B,C. 1D and 1. AC 0 is special 
since it can’t be used as a pointer, and it always contains very transient information. It is never used to fill in 
an ANY-AC slot in a DATUM. ‘The other five ACs are in the pool of available ACs. Objects of type AC have 
about ten different slots associated with them. ‘They are used for finding available ACs and generating output 
code that uses them. The slots used in AC alle 


jon are as follo 


L-ACLINK. If this is FALSE, the AC contains no temporary value for the current computation. 
Otherwise. itis alist of active DATUMs that contain it. 


2. ACAGE. "This is only used when the ACLINK is non-FALSE. It is updated w a higher number at 
cach use of the AC and is used in an ILRU algorithm when an active AC must be flushed. 


3. ACRESIOUE. If this AC is currently cqu 
the symboltable 


alent to some local variables, this slot contains a list of 
ntries for these variables. ‘The symbol-table entries themselves have a slot 
called TNACS that points back t the ACs that contain its (ype and/or value. ‘They also contain a 
slot culled STORED that specifies whether the only copy of the variable is in the ACS or it Is also in 
memory 


4. ACPROT. This slot isa boolean saying whether this AC is protected or not. If the AC is protected, it 
can't be allocated for any reason, Protection is unly invoked for very stretches of code. 
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S.ACPREF. This slot says that this AC deserves slightly preferential treatment, It means, all other 
things equal, don’t choose this AC. 


Ihe AC allocation algorithm consists primarily of trying to find the best possible candidate when an AC is 
needed. ‘The routine GETREG is used to find an available AC. 


rst it rejects all ACs that are protected (if they 


all are protected, the compiler generates an internat error since this should never happen), If there are one or 
more ACs with their ACLINKs FALSE, GETREG will choose from among them. It will prefer ACs with no 
ACRES IDUE, that are numerically adjacent to another frec AC (because some PIDP-10 instructions destroy the 
next AC), 


1d which do not have their ACPREFs.on, Ifthe AC chosen has an ACRESTDUE, code is generated 
it necessary to store any of the variables that are only in ACS. 


If no AC exists with un ACLINK that is FALSE. GETREG finds the AC with the smallest ACAGE, Code is 


generated te store the contents of the AC in a temporary so that it fs 


lable. “The DATUMS that were in the 
ACLINK are updated to indicate that they are now pointing to Cemporuties as opposed to ACs. “Thus it is 
possible that a generator could need sub-results in ACS, 


after causing one to be gen 


ed in an AC, find 
that while generating the second one the first slipped back into a temporary. “Ihe generator would then have 


to gener 


te code to reload an AC from the temporary. 


The CGP invokes various speciat-case optim 


ns by passing information up and down the tree as code 
js generated. ‘The generators for conditional branching FSUBRs like OR, AND a 


.d COND employ a predicate 
generator whenever possible. This generator is like GEM except that it takes three additional argument 


label to branch to. a flag saying whether to branch on truth or falseness. and a flag saying whether this 
predicate is being NOTed. ‘The general predicate generator then looks at the predicate node to see if it can 
take the additional arguments far predicate generation. If it ean, the general predicate generator just passes all 
the arguments down: otherwise it calls GEN and generates the additional testing and branching code itself: 
Currently AND, OR, COND, ==?, N==?, G7. G=?. L?, L=?, 02, 17, TYPE?, NOT. ASSIGNED?, MEMQ. 
LENGTH? and EMPTY? have special predicate code associated with their generators, Others may be added as 
the need develops. 


Other optimizations are invoked by simply recognizing common patterns of Mp}. code. For instance, the 
compiler recognizes <SET X <+ .X 13> asa PPP-10 AOS instruction and it generates very efficient code 
for <REST .X <- <LENGTH .X> 1>> by recognizing the pattern of code, 


“The compiler always takes advantage of as much knowledge as it has about the types generated by 
particular nodes to generate good code. ‘This is especially the case when it fs handling the code for NTH, REST 
‘and PUT in structures. It uses type information concerning the length of the structure and the amount being 
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RESTed for the NTH, REST of PUT. to figure out whether of not to gencrate bounds checks in the compiled 


code. Italso uses inform: 


on about the current type of the slot being read or written to decide whether not to 
read oF write the type Word. Obviously, a lot of this type information was the sume information obtained 
during the Analysis Pass of the compilation 


‘Some code generation routines are capable of changing the order of gencration of the sub-nodes. "This is 


done to try to get the node requiring the most ACs compiled first so th 


it won't Interfere with any AC 


requirements of the current node, ‘Thi 


usly requires that the commuted 


have no interacting side 
effects. 
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6. Making It Run Faster 
‘Once you have a working program, you will probably want it to nun fast. ‘The most obvious way of doing 


this is to compile it. Mbt. provides other ways to speed up code. chiefly by eliminating mediated subroutine 


calls, and by reducing the size of garbage-collected space. 


Mediated subroutine calls (or "MCALLs') are the standard method of function calling 


Mbt. ‘They 


Provide @ great deal of information and control during program development and debugging, but the 


d ofan MCALL is superfluous in debugged production programs. Consequently, several methods exist 


noving this overhead, 


A subtle impedi 


nt to increased speed in a production pro} 


am is the amount of time devoted to garbage 


collection, As this is proportional to the size of the garbage collected space. it is advantageous to make that 


space as small as possible. One w: cs in the MDL as. 


to do this is to purify as many of the static data structu 


possible, 


| ‘One by-product of the procedures mentioned above is that much of the resulting code and structure 


becomes pure and therefore shareable between many Mbt. processes. 


| 6.1. GLUE 
A facility cxists wo allow separately compiled and assembled RSUBRs to be ‘glued’ together. ‘This makes 
} calls between RSUBRs in the group much faster, as MCALLs are replaced by PUSHJs. “The many instructions 
of an MCALL are replaced by the single PUSHJ, but the mediation provided by MCALL is lost: No FRAME i 


| Produced. GLUEing is accomplished by the concatentation of the code and reference VECTORS of the RSUBRS 


being GLUEd, which gives them a common “frame of reference.” 


Additionally, GLUE is interfaced with the compiler such that: 


1. The RSUBRs can be run unGLUEd for convenient tracing and debugging. After debugging, they 
ean be GLUEd together and run much faster. 

2. An individual FUNCTION can be recompiled without the overhead of recompiling everything. 
GLUEd to its RSUBR. Aficr the recompilation, the entire set can be reGLUEd, 


6.1.1. How to Glue 


| 
| 60 


"GLUE is a PACKAGE and it may be obtained by doing 
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<USE “GLUE"> 
‘The call to gluc a group of RSUBRs and/or RSUBR-ENTRYS is: 


<GROUP-GLUE group-namezaton 
‘substitute:boolean 
seript:channel 
package:string-orlist 
survivors:list 
vietims:lis 


where: 


group-name is 


ATOM as returned by GROUP-LOAD, and it is the only required argument. 


substitute 0 Nag: ii i true. the current RSUBRs und RSUBR-ENTRYS will be fixed so that they may st) 

Bote a tnt. This is expensive but necessary If PRINTTYPEs or interrupt handlers are among the 

eens ta che group. If the fag is FALSE or not supplied. the group must be GROUP-DUMPed and 
Joaded before use. 


script Af supplied and a CHANNEL is used by GROUP-GLUE to print out its progress through lis task. 
‘Otherwise, GROUP-GLUE works silently 

package, if provided and non-FALSE. implies PACKAGE mode will be used 
Kos Nigh cpseitying the PACKAGE that is being glued. In PACKAGE mode only the ENTRYs of wat 
Boer nce ll be preserved and all RSUBR-ENTRYS associated with internal functions will be removed 
Thhis option can also se used by setting the ATOM PKG to the name of the PACKAGE. Package © y also be 
ae eT PACKAGE names, in which case the ENTRYS ofall the PACKAGES listed will be preserved. 


his argument should be a 


survivors if provided indicates that SURVIVOR mode will be used. ‘This argument should be a list of ase 
(OR -ENTRYs to be preserved. All other RSUBR-ENTRYs will be Mushed. This option, oversiets 


Ree aGE made. ‘This option ean also be used by sciting the ATOM SURV to the LIST of RSUBR-ENTRYS 
being preserved. 


victims allows “survivors to be specified by default; that is, k Is a LIST of those functions which should nof 
ave after GLUE has run. ‘This is sometimes more convenicnt to specify than explicit survivors, 
tmhere are two advantages to removing unneeded RSUBR-ENTRYs, ‘The group is made smaller by the absence 


of the RSUBR-ENTRYs. Also the code for the group is reduced, as the cade for handling MCALLS to those 
RSUBR-ENTRYS is removed. In gencral only the ENTRYS need to be kept for a PACKAGE. ‘This can be done 
by specifying the PACKAGE using PACKAGE mode, SURVIVOR mode should be used if the user wishes 19 


explicitly state which RSUBR-ENTRYs are to be kept. 


6.1.2. GLUE as a Program 


In addition to the "GLUE" PACKAGE, there is a program in which GLUE and PDUMP (sce section 6.3) are 


It will prompt for cach of the usval arguments to GROUP-GLUE, pe 
conveniently GLUE (and PDUMP) several PACKAGES in one session. 


preloaded. emitting the user to 
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6.2. Glue 


s 


GLUE is able to perform its transformations on compiled or assembled code with the aid of a data structure 


Produced during assembly. ‘This structure is called the “GLUE Bits 
by this FORM 
<AND <ASSIGNED? GLUE> 
-GLUE 
<PUT rsubr GLUE glue-bits:uvector>> 


I is an association placed on the RSUBR 


Thus if GLUE is non-FALSE the asswciation will be available to programs wishing to use it 


| Internally, the GLUE bits consist of two bits for each word af cade in the CODE clement of the RSUBR, 
followed by words specifying calling information. For cach INTERNAL 
alvin 


ENTRY in the code, there is a word 


ber uf a 


ments It Lakes und the offset of the INTERNAL-ENTRY in the CODE UVECTOR. 


‘The two bits fore individual instructions are 


ferpreted with the index field of the instruction as follows: 
| Bits 0 implics the instruction is uninteresting: 


Index field (M) and bits 1 in 


plies the instruction isa reference to the 


ode jiseIf(a jump, perhap: 


Index field (R) and bits 1 implies a reference to an impure slot of the RVECTOR (the compiler docs not 


generate such references); 
Index ficld (R) and bits 2 implies the instruction is an MCALL: 
Index field (R) and bits 3 implics the instruction isa reference to a pure slot of the RVECTOR. 


‘See section 7 for more details on the format of MDI. Assembly code. 


6.3. PDUMP 


MDL provides a mechanism for sharing compiled programs among several MDI. processes, and for 


dynamically moving the compiled code in and out of the virtual address space 3s space is needed in the 


interpreter. ‘This mechanism is described in detail in section 4.2. ‘This section describes how to convert a 


compiled program inw a sharable version, 


known as an FEIN (Fast-BINary) version of the program. 


First load the group-purifier, 


62 Glue Bits 
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<USE "PDUMP™> 
Next, GROUP-LOAD your group (or groups). 
GROUP-LOAD binans-filesstring> 
Which returns the group-name of the group. ‘This (and any other groups to be dumped together) is then 


passed to the pure-dumper: 


<PDUMP group-namel:atun group-name2saiom ... > 
his creates several files. only one of which you need be concerned with: 
sname: group-namel FBIM 


If given more than une group-namc, POUMP will create one FBIN file for cach group, but only a single FIXUP 


und sv single SAV file containing the fixups and code for all of the groups named. “The FIXUP and SAV files 


sre put on the "MUDTMP™ dircctory and eventually are inserted in the pure code library, as described in 


section 4,2 


Aternative methods of PDUMPing are to specify that as an option in to the program GLUE (sce section 


6.1.2), oF to use its preloaded POUMP dircctly after exiting its READER with ¥5. 


‘A warning about combining GLUE and POUMP: if you attempt to POUMP several groups that have been 


GLUEd together, you will lose. ‘This is because the references to the “group-RSUBR’ will fall on the wron; 


OBLISTs. 


PUMP also produces a structure analogous tw the GLUE bits (see section 6.2) produced by the compiler, 
out the RVECTOR of the RSUBR, for the use of PURIFY (see scetion 6.5). 


but containing only information 


6.4. SUBRFY 

SUBRification is a way of getting rid of many of the MCALLs which could not be practically removed using 
GLUE. Ifa FUNCTION is called by many separate groups, itis difficult to GLUE it to all the groups or to GLUE 
all the groups together. 


What 


.d with PUSH from 


really needed is to be able to allow something to be c arate groups 


without forcing it to be part of those groups. This is indeed the case with PUSHY entries to MDI, SUBRs (in 


the interpreter). A user can make his RSUBRs look like SUBRs in this respect. 


SUBRFY takes a group. which must be in NBIN format. It purifies the RSUBRs and RSUBR-ENTRYs in the 


group and changes them s that they can be ealled with PUSH. It also produces a file, known as the ‘preload’ 


file, which can be used by the compiler to generate PUSHJs to the functions in the SUBRified group. 
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SUBRFY should be lo 


ided before loading the group to be processed. The reason for this is that it 
guarantees that GLUE bits stay around. To load SUBRFY 

<USE "SUBRFY™> 
You should then GROUP-LOAD the group. Your group should be GLUEd already, since SUBRFY docs not 
GLUE the group together. 


SUBRFY can then be called in the following manner: 


<SUBRFY sroup:atom 
file-name:string 
output:channel> 


where 
group is the name of the group. 


file-name is the name of the file in which SUBRFY should put the information for the compiler, ‘This defaults 
to the name of the input file with second name "PRELOD™. 


‘ouput is.an optional argument which specifies a CHANNEL on which to print information about SUBRFY's 
progress. ‘The default is not to print anything. 


The file produced by SUBRFY should be FLOADed for compilations where functions in the SUBRified group 


are called. This cau be done by FLOADing it in the “Mhings to do’ part ofa COMMAT plan. 


Like purification, SUBRification changes the MPL. The only way to preserve the SUBRified group is to 
n be done 


SAVE the MDL. Before SAVEing the MDL the "SUBRFY™ PACKAGE should be removed. ‘This c 
by doinga 

<KILL-SUBRFY> 
followed by a 

<6c 0 T>. 


SUBRFYing a group implics that the group is not going to change at all frequently, if ever. A new 


SUBRF Yed SAVE file may be created at any time, and elements of the group may be recompiled. However, if 


the calling sequences of any of the functions in that group change, you invalidate any functions compiled 


Using the “pretoad’ file for that group. In short, think twice before tying yourself down with SUBRFY, 


6.5. Purification 


A facility exists wo permit the purification of Mbt. objects. Purified objects can be shared between MDL 


t examined by the garb 


ollector. What follows is a description of how this 


facility can be used, 
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The purification facility in Mot. is most useful in the creation of subsystems. Nun-purified RVECTORs of 


RSUBRs and tables used by subsystems are kept in garbage cullected space. ‘This means that these objects, 


which will never become garbage. are examined at cach garbage collection, slowing down the garbage 
collection process. Also, if two people are using the same subsystem, they cannot share the tables and RSUBRS 


kept in garbage collected space. Ry using purification these wo problems can be alleviated, 


I references 


UBR, “Me object will be purified. and a 


To purify most objects the user can call the PURTFY 
object. ‘This simple method 


to that object in the MDI. core image will be changed to point to the new 


se Of RSUBRS. Purification of RSUBRs Is a sev with 


ual step process best 


ot be used in the 


compilation. 


6.5.1. Purifying RSUBRs 
Once your FIN oF NBIN is ready you can actually do purification, ‘To do this first 
<USE “PURITY"> 
ins the routines needed w purify RSUBRs. ‘Then GROUP-LOAD the files you wish to 


This PACKAGE cont 
have purified. Once this is done ype 

<GROUP-PURIFY group:alum owtput:channel> 
This will purify and link all RSUBRs and RSUBR-ENTRYs in the group and will also attempt to purify any 
RSUBRS or RSUBR-ENTRYs called by the group. Giving the optional channel will cause GROUP-PURIFY to 


print information concerning the progress of the purification. 


ete, use the 


GROUP-PURIFY will only purify RSUBRs and RSUBR-ENTRYs. In order to purify tabl 
PURIFY SUBR directly. Since purification is an extremely expensive operation, it is recommended that you 
collect together the things you wish to purify into a LIST, VECTOR, etc. and purify that structured object. 


‘Once purification has occurred, several things may be done tw recover wasted garbage collected space. 
‘The user can get rid of the "PURITY" PACKAGE by doing a 
<kILL:PURITY> 
The user can also remove much of the overhead of keeping a group around by UNASSIGNing the 
sroup-name. Removals of this type should be follwed by an explicit call w the garbage collector invoking the 
tions. ‘This can be done by 


hairy’ GC feature, 
<Gc 0 T> 

In order (o save a file with purified Mist. objects you must SAVE. Restoring a SAVEd file with puri 

‘objects will cause those objects to share with any other MDL. RESTOREd from the same SAVE file. 


h of the storage to be regained is pointed to by assoc 


ied MDI. 
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| 6.5.2. Purifying an Environment 


Many subsystems maintain a list containing pointers to all the static data structures built by that 


subsystem: dispatch tables, data bases, and so on. The list can be given to PURTFY to move all its components 


into the pure area. However, there are other structures 


garbage collected space that may be purified; ¢8., 
| the RVECTORs of RSUBRS, RSUBR DECLs, and soon. 


The "CLEAN™ PACKAGE examines these structures, luoking for those which may be purified. It may also 
bbe used for informational purposes. To get it 
<USE "CLEAN"> 
"CLEAN™ has one major ENTRY, CLEANUP, which examines every ATOM of every OBLIST in the MDI. It 
may perform a Variety of functions, but it is most often used to make DECLs share storage and to accumulate a 
LIST of purifiable structures. Ail of its arguments are optional, 
<CLEANUP print?:boolean 
reset?:boolean 
decl?:boolean 
sdecl?:boolean 
pure?:boolean 
check?:boolean 
avoid: list-of oblists> 
print? is by default FALSE. If non-FALSE. information about cach ATOM examined will be printed as 
CLEANUP runs. Thisis a fof of information. 


reset? is by default T. Ifnon-FALSE. the LISTs of objects previously collected will be resct before CLEANUP 


deci? is by default T. If non-FALSE, cach DECL clement will be made to exist exactly once in the entire core 
2 image. F_g., there will be only one copy of the DECL <LIST [REST F1X]> inthe core image. 


sdecl? is by default T. Its similar to deci?, but refers to GDECLS 
= pure? tells whether to make a LIST of all the purifiable objects in the core image. It is by default T. 


check? tells whether to make LISTS of all the TYPEs, RSUBRs, RSUBR-ENTRYS, cic. in the core image. Itis 
by default T. 


avold is a LIST of OBLISTs not to look in: it is by default the OBLISTs associated with "CLEAN™ and 
"PURITY". 


CLEANUP roturns (if pure? is non-FALSE) a structure (also stored as the GVAL of PURELST) which may be 
» given to PURIFY. 


The results of running CLEANUP may be examined by 
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<PRINT-CLEANUP> 
As the object in running CLEANUP is to shrink the size of one’s MDL and its garbage-collected space, it is 
useful to be able to remove CLEAN after it has done its work. 

<FLUSH-CLEANUP> 
the PACKAGE from the MoL 


removes everything associated w' 


6.5.3. Purification Summary 


In a simple case, one can purify a“subsyst wp maximally by 


<USE "PURITY" “CLEAN"> 
<GROUP-LOAD “foo"> 
<CLEANUP> 
<GROUP-PURIFY foo> 
<KILL:PURITY> 
<FLUSH-CLEAMUP> 

<Gc 01> 

<SAVE “foo™> 


6.6. TEMPLATES 


The PRIMTYPE TEMPLATE cuts down on the need for storage by allowing the user to specify exactly what 


he wants. structured object to contain, similar to ‘structures’ in PL/L or C. 


To use this feature one must er TYPE of PRIMTYPE TEMPLATE. This can be accomplished by 


using the RSUBR TEMPLATE. ‘The procedure for doing so is: 
<USE "TEMPLATE™> 


<TEMPLATE namezarom ... specs... > 
where name is the name of the new TYPE and specs are specifications for each clement of the TEMPLATE. 
This returns the TYPE name of the TEMPLATE and creates a creator of TEMPLATEs of TYPE name, called 


name itself, which can be applied to arguments to create objects of that TYPE of TEMPLATE. 
The specification for the elements can be of several forms. Itcan be one of 


A TYPE: type:atom 


Jement LIST: (1ypecatom length:fix) 


a 3-clement LIST: (1ypesatom length:fix count:fix) 


Below are some examples along with explanations: 


tion 6s 


| yr 
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List 
isan 18 bit LIST pointer. 
(FIX 18) 


ord FIX (can be both positive and negative and is checked for overflow). 
(FLOAT 18) 
is an 18 bit FLOAT (which is the left halfword of a ‘normal’ FLOAT and therefore somewhat restricts the 


precision). 
(FIX a) 

(where mis less than 18) js 
BOOLEAN 

is not a MDI. TYPE, but a one bit FALSE or non-FALSE depending on whether the bits 0 oF 1 

(UVECTOR 18 7”) 

18 bit UVECTOR pointer. Mhe UVECTOR is of 

(STRING 36 n) 


positive FIX of | 


\gth 1 bits (is not checked for overflow). 


th n. The same can be done for VECTORS, 


is a 36 bit string byte pointer. ‘The STRING is of length n. 
ANY 


f to use in TEMPLATES as it takes 


is nota MDI. TYPE, rather anything can go here, This is relatively ineffic 


up 2 words. 


In order to provide more flexibility in using TEMPLATES, two other fields are allowed, an optional field 


id a rest field. ‘The optional field allows the user to create TEMPLATE TYPEs which will have the same basic 
tual TEMPLATE is created. ‘The rest 


field. like the optional field, allows clements to be optional but specifies a pattern for any elements that are 


structure but which can have uptional elements determined when th 


added on. It is analogous to REST in DECLs. Scparation of fields is accomplished by the use of the strings 
"REST" and “OPTIONAL”. For example: 

<TEMPLATE FOO FIX “OPTIONAL” LIST BOOLEAN "REST™ FLOAT> 
This creates a TYPE FOO of PRIMTYPE TEMPLATE which always has a FIX as the first element, can have a 


LIST as a sccond clement, can havea one bit Tor #FALSE (as the third clement and can have any number 


of FLOATS from the fourth element on, 


6.6.1. Use of TEMPLATES 


TEMPLATE TYPEs may be thought of as primitive TYPEs, in that they each have a 


nique storage 
representation. On the other hand, the TYPEPRIM of any TEMPLATE TYPE is TEMPLATE. A primitive 


TEMPLATE (which cannot truly exist in the language) would look like 
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( element element-2 ... elemenrn } 


Real TEMPLATE TYPEs are represented as WEWTYPES of this primitive TEMPLATE TYPE. 

miype-name { ... elements... } 
his method is similar to the usual method in Mbt. for representing any new TYPE, in that a RESTed 
TEMPLATE will be printed “CHTYPEd to its PRIMTYPE.” Note that a TEMPLATE so printed cannot be read by 
READ 


primitive TEMPLATE" cannot exist. It Is best to avoid printing RESTed TEMPLATES. 


Below are some examples of the use of TEMPLATES. 
<TEMPLATE BAR 
FIX 
OPTIONAL” BOOLEAN 


“REST™ (FIX 18) (FLOAT 18)>S 
BAR 


<BAR 15 
wear (1) 


<BAR 1 TDS 
#oaR {1 1) 


<BAR 1 <> 1 1.035 
WBAR (1 #FALSE () 1 1.0) 


<SET A <BAR 1 <> 1.1.9 2998 
#BAR {1 #FALSE () 1 1.8984375 2} 


<PUT .A 1 6>S 
WBAR (6 #FALSE () 1 1.8984375 2} 


<PUT .A 4 1.999>S 
WBAR (6 #FALSE () 1 1.9960937 2} 


TEMPLATE BAR (STRING 36 4) "REST" ANYDS 
WFALSE ("ALREADY A TEMPLATE") 


TEMPLATE BARI (STRING 36 4) "REST" ANY>S 
BARE 
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13 
<SET A <BARI “HELP” 2 () <>>>5 
WBAR1 ("HELP™ 2 () #FALSE ()} 
<PUT .A 1 "GoOD">S 
WBAR1 ("GOOD" 2 () MFALSE ()} 
<PUT .A 1 *GOOD-BYE">S 
TERROR? 
TEMPLATE-TYPE-VIOLAT ION 
pur 
LISTENING-AT-LEVEL 2 PROCESS 1 

6.6.2. Assembly of TEMPLATES 

Once u set of TEMPLATE TYPEs is created, as for the TYPE definitions of a subsystem, it saves time to 


store away the “compiled” TEMPLATE generators and not recreate them each time the definitions are to be 


used. 

The “TEMMAK" PACKAGE mudifics files which define TEMPLATE TYPEs to contain the TEMPLATE 
descriptions and RSUBRs rather than the calls to TEMPLATE. It is only usefil, of course, when the 
TEMPLATES are defined in a file which will not normally be edited, since the new files are in ‘NBIN* format. 
To load this PACKAGE 

<USE "TEMHAK"> 


The PACKAGE has two entries. 

<TEMPLATE-DUMP  group-namecaiom> 
lakes the group and modifies it such that <USE “TEMPLATE"> becomes <USE “TEMHLP”>, and all 
top-level invocations of TEMPLATE are replaced by calls to BUILD-TEMPLATE (for the TEMPLATE 


descriptions), SETGs of the TEMPLATE-gencrating RSUBRs, and the GLUE bits for the RSUBRs. 


<FILE-TEMPLATE iuput:sirine output:string> 


takes an input file 


.d performs the same se 


GROUP-DUMPing the result to the optional ouput file (by 
default the same file with second ni 


me “NBIN™). ‘This is useful fur files which contain nothing but TYPE 


definitions, a common practice in large subsystems, 


Ifthe TEMPLATE TYPEs are defined 
used after creating the TEMPLATE TYPEs: 


1 a file which will be edited frequently, a different set of routines is 
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<OUMP-TEMPLATES 
places the TEMPLATE descriptions (of the RSUBRs) in the specified descriptions file. It docs so for all 


scriptions:string> 


TEMPLATE TYPEscurrently defined. 


<DUMP-RSUBRS rsubrscstring Lemplate-ppe:atom > 


will perform the same service ir the TEMPLATE-generating RSUBRs of the TYPEs given as the second and 


later arguments to UMP-RSUBRS. 


There will now be two files, one containing the TEMPLATE descriptions and the other the RSUBRs. ‘These 
may now be used to create the TEMPLATE TYPEs without USEing "TEMPLATE". ‘To doo: 
USE "TEMHLP™ 


This defines the RSUBRs needed to uke and make them useful to MDL 


he TEMPLATE descriptic 


FLOAD descriptions:string> 
the file of descriptions (the file created with DUMP-TEMPLATES); this must be loaded before the RSUBRs 
file. ‘Then load the RSUBRS file (the file created hy DUMP-RSUBRS) 

<FLOAD rsubrs:siring> 
For maximum convenience, it may be necessary to put a FORM In files that create TEMPLATES: if the 


TEMPLATE files described here exist, FLOAD them; otherwise, <USE “TEMPLATE"> and create the 


TEMPLATES from scratch. It is of course possible to manually merge the two TEMPLATE definition files 
(preferably by using GROUP-LOAD and GROUP-DUMP), so long as the TEMPLATE descriptions precede the 


TEMPLATE RSUBRs. 


TEMPLATE RSUBRs are created with GLUE bits, so it is possible to glue them into groups and to purify 


them. 
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7. The Assembler 
ht 
of the operating system not available in the interpreter. ‘The MDL assembler (which is also used by the MDL 


‘occasionally necessary to write MDL routines in assembly language, usually to interface with a feature 


compiler) provides this ability. 


7.1. The Assembler 
The Mp. assembler provides the MDI_user with a means of writing RSUBRs directly in machine language. 


The asse nguage of the compiler, This section is a description of the 


ber is also used as the object I 


ssembler, 


\d some of its pscudo-operations. 


7.1.4. General Organization 
The Mbt assembler is written in MDI to produce code that runs in the MDI. environment. It takes 
nents in the following form 


<FILE-ASSEMBLE iuput-file:string 
output-file:string 
quick:boolean> 


argu 


The arguments are a 


inpur-file containing Mp1. assembly code (possibly for several RSUBRs), an optional 


oulput-file in which to put the binary output (by default the same file as iupur but with second file na 


*NBIN™), and an optional third argument which tells whether to use NBIN format output, and which under 


normal circumstances should always be T. ‘There are four other optional arguments which are the same as the 
second through fifth arguments of ASSEMBLE. 


<ASSEMBLE body 
tocals 
messages 
ist 
symbols> 


(All the arguments are optional with the exception of body.) 


body may be a CHANNEL, in which case all Instructions in the file associated with the CHANNEL are assembled, 
or it may be a structured object, in which case all instructions in the object are assembled. 


reals specifies the OBLTST to use for local symbol lookup when the budy is a CHANNEL. ‘The default is 
<1 .OBLIST> when the assembler is called. 


‘messages is & CHANNEL to receive error messages, etc. It defiults to . MESSAGE-CHANNEL. 


list is a CHANNEL to receive an assembly listing. If list is not supplied, no listing is gener: IF fist is a 
Non-FALSE non-CHANNEL, and messages is a CHANNEL, then the messages CHANNEL will receive the 
address of cach label. If list is a FALSE, then no listing is produced, ‘Ihe default is . LINE-CHANNEL 
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(Initially LINE -CHANNEL Is FALSE.) 


symbols indicatcs if true that a DDT symbol table of all the labels for use with "RDB™ (see section 7.2) will be 
generated. ‘The default is .MAKE~SYM-TABLE (Initially MAKE-SYM-TABLE is FALSE.) 


7.1.2. The Assembler as a Program 


The assembler also exists as program called ASSEM, which encapsulates F ILE~ASSEMBLE 


7.1.3. Format of Assembler’s Source | 


The Mint assé line of cade is a FORM. It assembles FORMS into instructions in much 


or's equivalent « 


the same way that a typical assembler treats lines of source code, ATOMs at the tp level (i.e, nut in FORMS) are 


treated as labels. ‘The FORMS arc assembled bused on the TYPE of the GVAL of the first ATOM in the FORM. 


The GVALs of ATOMs whose PNAMES arc the PIDP-10 instructions are of TYPE OPCODE (PRIMTYPE WORD: 


the ‘value word’ has the 36 bit value of the instruction. For example, in 
<MOVE A 1 (B)> 
the value of MOVE (in the OP OBLIST) is 4OPCODE *200000000000*. ‘This FORM is assembled directly 


into an instruction. 


If the GVAL of the first ATOM in a FORM is something applicable (SUBR, FUNCTION, RSUBR ctc.) the 


FORM is EVALed and the resulting SPLICE of FORMS is assembled. ‘This is how macros and pseudo-ops are 


implemented. Notice that a pscudo-up or macro may produce no code by returning an empty SPLICE. 


7.1.4. Instruction Assembly 

Having determined that a FORM is going to assemble into an instruction, the assembler basically adds up 
the values of all the items in the FORM. In the case of items of TYPE OPCODE. a full 36 bit add is performed. } 
Items of TYPE ADDRESS refer to labels in the program. Since the code is all location insensitive and will | 


move around during garbage collection, references to labels must be indexed by accumulator M, the base 


register. Therefore, label symbols include an M in the left half and must also be added in with a full-word add, 
loms of PRIMTYPE WORD other than OPCODEs and ADDRESScs are ANDBed with *777777* before being 


udded, and the carry from right half to left half is suppressed, When ATOMS are found in FORMs that are being 


assembled into instructions, special lookup rules are in effect. If the ATOM has a global value, that value is 


used. [Fthe ATOM docs not have a global value but has a local value, it is used. Ifthe ATOM has neither a focal 


or global value, it is assumed to be a le 


hus already been defined, otherwise it is added tw a list uf as yet undefined symbols, 


al symbol for this assembly. In this case the symbol valuc is used 
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‘Objects other than ATOMs or PRIMTYPE WORDs cause the assembler to take special action. 


— LISTsare used to Indicate swapping left and right halves. For cxample 
MOVE (1)> 
would put the 1 in the index ficld of the MOVE instruction (similar to MIDAS), 
— A VECTOR indicates a constant. The VECTOR may contain any number of FORMs to be assembled 
| at the end of the program. example: 
<PUSH TP* [<1 (1)>]> 
pushes a co 


stant containing | in the right and let halves. 


— A FORM is simply EVALed and the value retu 


od is used. 


7.1.5. Initial Symbols 
The OBLIST structure in effect during assembly is 
(op md! DEFAULT local root) 
Phe OBLIST op is nated OP 


ins the PIDP-10 opcodes, the MI. accu 
accumulator and address fields). and the pseudi 
of 


tions (in both, 
‘ops. The OBL IST md/ is named MUDDLE and contains values 


ny labels in the interpreter. ‘This enables programs to do things like <JRST FINIS>, the standard way 


to exit From an RSUBR. When an instruction is assembled using a symbol from the MUDDLE OBLIST, a fixup 


is also generated so that. if the symbol gets a different value in a new Mbt. the eode can 


fixed up when it is 
loaded. Local is the user's local symbol OBL IST and roor is the ROOT OBL IST. 


As stated earlier, every accumulator has two symbols associated with it, one fir the address field and one 
for the accumulator field. ‘This is because there is no syntax to specify which ficld is intended. ‘The address 
symbol is simply the accumulator’s name, and the accumulator symbol is the name with an asterisk (#) 
appended wo it; e.g, A versus A 


7.1.6. Macro Writing 
Whenever an clement or subelement of an instruction is a FORM and the first clement of the FORM has an 


APPLICABLE GVAL. the FORM is evaluated and the result (unless it is a SPLICE) is re-eval 


ied as if it were 
im place of the FORM, ‘This feature constitutes the assembler’s macro facility. 


For compatibility between “top-level” macros, which generate whole instructions, and macros which 
Senerate parts of an instruction, top-level macros may wish to return several instructions, ‘To indicate that 
‘shat is rewrned is several instructions, itis necessary to return an object of ype SPLICE (PRIMTYPE LIST). 
The clements of the SPLICE are treated 


instructions. An empty SPLICE may be retwrned from 


at ‘The Assembler 
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a macro which is part of an instruction, and the effect is as if a 0 were returned. "This is the only SPLICE 


which may be returned from a macro which is a part of an instruction. 


7.1.7. Pseudo Operations 
The next part of this document will describe pscudo-ops available in the Mp1. assembler. “There is no 


difference between a pscudo-op and macro in the assembler except that the pscudo-operations are supplied 
by the system. 

<TITLE name:string> 
This is about the only required pscudo-op. It must be the first instruction to be assembled. It takes one 


argument. the name of the RSUBR being assembled. If additional TITLEs are found in a file by 


ng 
ssembler prints each 


assembled, they are assumed tw both end the previous RSUBR and begin the next. ‘he 


TITLE on the messuges CHANNEL as it is encountered. 1 
<SUB-ENTRY euiryzatom dec> 
This pscudo-op is used to define additional RSUGR-ENTRYs for the RSUBR being assembled. ‘The eniry 


argument is the name of the RSUBR-ENTRY 
<INTERNAL-ENTRY cuirv:otom args:fix> 
is used w create an INTERNAL-ENTRY for a GLUEable RSUBR. Its arguments are the name of the 


1d the optional dec! argument is a DECL for the entry. 


INTERNAL-ENTRY and the number of arguments that will have been pushed on the stack for it when it is 
called. Sce also section 7.1.9 for details on writing GLUEable RSUBRS. 

<DECLARE (“VALUE™ decl dec! decl ...-)> 
is used tw supply declarations for the RSUBR named in the TITLE. It must occur before any code-generating 
instructions. DECLARE takes a LIST as its one argument. “The format of the LIST is as described in [3]. The 
string "VALUE™ is optional; if supplied it causes the first dee! to declare the TYPE of the value of the RSUBR. 
ch additional dec! is associated with one argument. Special STRINGS may also appear in the LIST with the 


following meanings: 
"QUOTE The next argument is QUOTEd (not EVALed). 
"OPTIONAL" ‘The rest of the arguments are optional (the RSUBR must supply any defaults for these). 


"CALL" If this appears, it must be directly after the "VALUE" dec/. It says there is one argument and it is the 
FORM generating the call (sce “CALL” for FUNCTION in [3)). 


ARGS" ‘This must be the last STRING. {t says treat the rest of the arguments in the FORM as a LIST and 
pass it as the argument (see "ARGS" for FUNCT IONs in [3)). 


“TUPLE™ EVAL the rest of the arguments and pass them. 
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<END> 

indicates the end of an RSUBR or group of RSUBRs. Only the text between TITLE and END pscudo-ops will 

be processed by the assembler. ‘This makes it possible to intermix assembler source code and normal MDL, 

source code in the same file (although assembly must be done before compilation in such cases). 
<TYPE-CODE pe:atom> 


allows references to 


internal TYPE codes for both system and user defined TYPEs. It takes one argument, 
the Mbt TYPE name. For example: 
<MOVSI A* <TYPE-CODE FIX>> 
puts the TYPE code for FIX into the left half of accumulator A. 
<TYPE-WORD ppecatom any ... > 
generates a reference to a word containing the TYPE code for He in the left half and possibly other junk in 


the right hulf. ‘The first argument is the TYPE name and the rest of 


arguments are optional but if-supplied 


are added into the right half, If the TYPE is an initial TYPE and no right half is generated, a reference to the 


‘ST Hype toca 


ion in the interpreter is generated. For example, 


<PUSH TP* <TYPE-WORD FIX>> 
<PUSH TP* [0}> 


would push a FIX 0 on the stack. 
GETYP a tupecatom> 

has the same form as a PIDP-10 instruction. It gets the TYPE code for (ype into the right half of its 

accumulator from its address. This is done by generating an appropr 
<MQUOTE obiectzany> 


allows the RSUBR to reference garbage collected space. It adds its argument to the RVECTOR (if it isn't 


ite LOB (load byte) instruction, 


already there) and evaluates to an address of the form offte/( R). pointing to the value word for object. 
<PQUOTE obiectam> 
is Identical to <<MQUOTE objectzany> -1> ic. it points to the type-word, not the value-word. ‘This is a more 
consistent way to look at things. 
SIQUOTE objectzany label:atom> 
is like PQUOTE except that this will add a new clement to the reference VECTOR cach time called, The 
optional label if given defines the ATOM to be a label referring to that clement. ‘This is the only way to refer to 
that clement again. 
<PSEUDO argsany> 


valuates its argument for its side effects and assembles no code. 
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<SIXBIT siting? 
makes SIXBIT of the legal characters of string. 
<SQUOZE wring sqbits:word> 
makes SQUOZE of the legal characters of string and sticks the low-order four bits of the optional sqbits in the 
high-order four bits of the value, See the MTOAS Manual [4] for an explanation vf the SQUOZE code. 
<BYTE bowidan:fix bytesize:fix location> 
Example: <BYTE 1 38 (C) 1>islike<(*014300%) (C) 1> 
<ARG arsuum=fix> 
istike €(AB) <* 2 <= -argnum 13>. ARG should not be used in GLUEable code. 
STACK sumilcatom symn2:atom syn3zatom «> 
makes synt 


symbol for (1B) 0>, sym2 a symbol for <(TB) 2. syn1F a symbol for <(TB) 4, cle. 
STACK should not be used in GLUEable code. 


<OPUSH ac ares 
<OPOP ac ares> 
<DMOVE ac are? 
<OMOVEM gc args> 
are the double-word PDP-10 instructions. For example, 
<DPUSH ae args> 
expands into 
WSPLICE (<PUSH ac args> <PUSH ac args 1>) 
<UNDEF? sumbol:atom> 
xes to true only if the symbol has previously In the code been used as a symbol. but has not been 
defined. 
<IF-NEEDED smbolzafom instructions ..~ > 
If <UNDEF? symbol> evaluates to true, then all the instructions arc inserted at the current location, otherwise 


eval 


they are not. 
<*INSERT file-spec:siring> 
takes file and reads instructions from it and inserts the instructions read at the current place. 


7.1.8. The Type RSUBR 
An RSUBR is a Mi 
CODE (or PCODE). CODE 


object of PRIMTYPE VECTOR. ‘The first clement of an RSUBR is always of TYPE 


of PRIMTYPE UVECTOR, consisting of words or instructions. ‘The second element 
of-an RSUBR is an ATOM which is the RSUBR's name. If the RSUBR has declarations they are the third 
element. ‘The rest of the RSUBR contains MDL objects which must be referenced by the code 
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‘An RSUBR-ENTRY is a VECTOR of two or three items. ‘The first item is cither an RSUBR or an ATOM 
whose GVAL is an RSUBR, the second is an ATOM which is the entry's name and the third is a DECL for the 
nity. “The difference betwen an RSUBR and an RSUBR-ENTRY is that an RSUBR always starts running at 
the beginning of the code when itis called while an RSUBR-ENTRY usually starts running somewhere in the 
middle of the code. 


7.1.9. Writing Gluable RSUBRs 
Certain conventions must be followed when writing hand coded RSUBRs in order to get the must benefit 


from GLUEing. If the RSUBR (or RSUBR-ENTRY) has * 


'UPLE™ in its DECL, it is already in the best shape 


after the TITLE 


possible. In all other eases, the cod SUB-ENTRY pscudo-operution should simply push 


the arguments onto the TP stack and PUSH P* 1 une of the internal entries based on the number of items 


on the stuck, Afler the PUSHI it should do a <IRST FINIS>. An internal entry is set up by using the 


INTERNAL-ENTRY pscudo-op which takes two arguments: an atom and a fix. ‘The alum acts ws iit were a 


label on the next instruction a bel. The fix specifies how many items (type-value pairs) 


id may be used as a t 


are on the stack at this internal entry. In the s 


nple case where there are no optional arguments, only one 
internal entry exists and its number argument is exactly the required number of arguments, If optional 


arguments exist, sume kind of dispatch will have to be done. 


{in the rest of the body of the RSUBR, no references to AB oF TB (through the ARG or STACK pscudo-ops or 
directly) can be made, because afer GLUEing their contents may be meaningless, All references to the TP 
stack must be indexed by TP. The usustl precautions concerning the possible movement af code if'an INTGO 
OF MCALL is done also apply (i.e. the use of <SUBM M* (P)> at the beginning and <IRST MPOP3> at the 
tend of the code are essentially mandatory). 


7.2. Debugging Binary Code 
inary code produced by the Mp1. assembler or the Mot. compiler may be debugged with DDT, like any 


other binary code. However. an interface between that code and the DDT environment must exist, ‘That 


interface is the "RDB™ PACKAGE. It is obtained by 
<USE "ROB*> 
The sy 


ly produced by the assembler can be passed w DDT and at the same time the 


bol table option 
RSUBR frozen (moved out of normal garbage-collected space) by: 
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<RFREEZE name-of rubrcalom> 
Note that name-of'rsubr may also refer to an RSUBR-ENTRY, 
<RBREAK nomeofrsubr:atom> 
is similar, but in addition causes DDT to puta breakpoint at the first instruction of the RSUBR 


If there is no symbol table, RFREEZE and RBREAK merely freeze the RSUBR and pass up symbols for the 


RSUBR nam 


and any sub-entries. 


tn all eases the symbols passed up are made up of the legal SQUOZE characters (letters, digits, 1S. 1\%, 


1N.) ofthe n 
<ADR gbjectzanv> 


returns the address of object as a FIX, For © 


me. up to six characters. For example the ATOM FOO-*BLECH becomes the symbol FOOBLE, 


mple, ADR. rsubr> would return the location of the rsubr in 


core, 
<RUNBREAK name-ofrsubr:atom> 
clears the breakpoint(s) at the beginning of the RSUBR and of any of its sub-ntries. 


7.3. Unassembling Binary Code 


Converting compile } or assembled binary cude back into something resembling the original ass 


source code is an operation that is performed primarily in one situation: tracking down a Mp1. compiler bug. 


It is, however, almost in’ 


luable in that situation. ‘The PACKAGE containing the unassembicr is "UNASSM" 


‘The main entry is 


<UNASSEMBLE code:rsubr-or- group 
‘output:channel-or-string 
glue?:boolean> 


cade is the object being unassembled. Its cither an RSUBR (not an RSUBR-ENTRY, note), or an ATOM whose 
LAL is a group (as created by GROUP-LOAD). 


oulput is where to put the output: iF it is a STRING. then the output is put in a file with that name, If output is 
CHANNEL, then output is done on that CHANNEL. ‘The file is "code UNASSM™ by default. 


glue? (by default T) tells whether there are glue bits for the code loaded. If there are none, this argument 
should be given asa FALSE. 


‘The output produced by UNASSEMBLE is like the Mbt. compiler’s assembler input, with the addition of 


rents which give code and stack offsets for stack slots referenced. ‘This inform: 


con jon is useful in tracing 


exactly what is going on in the code, but it ts not always accurate, since the compiler's stack model Is 


sometimes too complex for the unassembler to understand. 
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Mp compiler bug reports are expected to contain MDL. source and UNASSEMBLEd compiled code if 
Possible. 
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8. Informational Aids 
This chapter discusses a few programs, most written in assembly language rather than MPL, which are 


nonetheless of use to MDL. programmers. Most are informational aids of one sort or another. ‘They include: 


MUDCOM, a program for comparing versions of a MDI. program, It is used by COMMAT (sce scetion 5.2) to aid 
in the preparation of compiler plan files. Ithas several useful aliases. 


Mar. the Mp ‘atsign’ program, produces listings, indexes and cross-reference 
similar program wh 


for Mb}. programs. ®, a 
is not Mt -specific, will perform approximately the same tasks. 


MUDINO fs an interface to the ITS IPC device and is therefore a means of intera 
the IPC device 
of compilations. 


ting with any Mit that has 
bled. It has an alias, STATUS, which is particularly useful for determining the progress 


8.1. File Comparison and Checking with MUDCOM 


MUDCOM is an assembly language program (not written in MDL), which nonetheless underst 


syntax of MDI. programs. It is used for comparing two versions of the same program. and also (4 


name MUDCHK) for checking the syntax of MDI. source files more rapidly than they can be loaded into a 


Mbt. MuDcoM is not interactive: all instructions must be passed on the je! line. 


MUDCOM understands the following MDL structures at top level 


FUNCTIONS <DEFINE FOO .....> 
MACROS <DEFMAC BAR .....> 

GVALs <SETG MUMBLE ....> 

LVALs <SET MUMBLE .....> 

MANIFEST 

PACKAGE 

ENTRY 

ENDPACKAGE 

MSETG <MSETG FOO 1>is<SETG FOO 1> <MANIFEST FOO> 


The jel for MUDCOM in the simplest case is filename! filenam: 


MupcoM will compare the two files and 
Print out information concerning those structures it understands which have been removed, changed, or 
inserted. 


Muncom has a number of switches which can be set. “They are given as /switch, where switch is the name 


of the switch, Currently the followin 


T prints totals at the end of the 


L prints all FUNCT IONs and GVALs in the file. 
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C checks the file given for syntax (only one file name at a time). 


M checks the files for changed MACROs and MANIFESTS In this mode, MUDCOM will make a second pass 
through the first file given in the je, looking for ull occurrences of calls to changed MACROs and 
MANIFESTS. MUDCOM will consider FUNCT IONs making such calls as having becn “changed” and will tell 
which MACRO or MANIFEST caused the ‘change’. 


The following other jel is understood by MUDCOM: 


(atom... Yappearing before the file names in the je! will cause MUDCOM to think that those FUNCT IONS 


ged and will print them as such. 


“filename” appearing anywhere in the jel causes commands to be read from that file until the end-vF-file is 


reached. 


(Ultename ..~ ) is used to specify fites to search in calls to MUDEND (see below). 
Aliases of MUDCOM: 


1, MUDCHIK. MUDCHK filename checks a 
MUDCOM /C filename 


file for MDI. syntax errors. "This is the same as 


2. MUDISt. MUDLST filename lists ull FUNCT LOMs and GVALs found in the file, This is the same as 
MUDCOM /L filename 
3. MUDEND. :MUDEND atom ... (ile file) searches files for FUNCT IONS/GVALs called atoms. It 
can be used for finding a FUNCTION in a haystack. “This is the same as 
MUDCOM (atom atonr) (file file} 


Since typing this can be tedious, it is easier to use the "f i1ename™ convention and have a disk 
file containing the files to be searched (surrounded by (}s). Thus, 


MUDFND FOO BAR BLETCH "MARC:ZORK FILES™ 
will look for the typical FUNCTION names in the files specified in MARC;ZORK FILES. 


8.2. The MDL Listing Program MAT 
Mat is a program for producing listings of Mt. programs on the Xerox Graphics Printer (XGP) or a 


lineprinter. (MAT is short for*MDt. Atsign’, after the general listing program named @). 


Resides a listing of the program itself, MAT includes a symbol table ~- a list of defined objects (arguments to 


DEFINE, SETG, etc.) and optionally a cross-reference listing ~ a list of every place in the program cach ATOM 


Is used. MAT can alsoa 
that have changed will be printed. 


produce a record fic, so that the next time MAT is nun on the same program, only pages 
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MA‘ is invoked with a je! fine in the following format: 

MAT Irec=oulputinput-files ... /switches ... 
More specifically. it takes any number of input files (separated on the Je! line by commas) and produces a 
listing of them in the ou!pur file, with options specified by the switches (each preceded by a /, 
record file /ree (see section 8.2.4). 


nd optionally a 


The ou/put file name defaults on ITS to xuname: input @ or @XGP depending on whether the X switch is 
used, and on Tenex/TOPS-20 to input. MAT oF input. XGP in the connected directory. 


8.2.1. MAT Switches 


The specific sorts of options available in MAT 


controled by a variety of switches which determine such 
things as whether to produc 


cross-reference listing, whether to use the XGP as the output device, and so 
on. ‘The following switches are impl 
“ 


causes a cross-reference listing to be produced. ‘This is 


table showing each reference 10 each ATOM (other 


than SUBRs, FSUBRs, and locals) in the input files. 

/0[file-name} 
specifies file-name as the file containing the user's definitions. Definitions are discussed in detail below. 

/¥ [text-font , header-font . comment-font] 
specifies the XGP fonts to use in the ousput file. They are respectively the font to use for the program itself, 
the font for subtitles and other headers, and the font for MDt. COMMENT and wp-level STRINGS. ‘The 
default directory is FONTS and the default second file name is KST. ‘The det 
a /X to be performed. 

/1Lfile-name} 


It font is 20FG. /F also causes 


specifies a file which contains the names of input files. “This is in licu of typing them all in each time MAT is 
Fun, useful for large subsystems incorporating many files. ‘The input files listed should be separated by 
commas or carriage-returns. 

™ 
causes output of only the symbol tables and cross-reference listing (if specified). No heading or title pages are 
produced. 

a” 


VPS, VALRETsa : PROCED to DDT and continues. Useful for long MAT runs. 
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QL message] 
prints message at the bottom of each page. ‘The 


mR 

creates a record file (this is automatic if “Irec=" is used). See below for details about record files. 
1s 

outputs cach file in a multiple file listing separately, 


/T Enamel name2y 
specifies names to use on the title page (in licu of the file names of first input file), 
“a 


arate symbol table for each type of defined item in the /npu file(s) (e.g, FUNCTION, GVAL, ete). 


* 
declares that output is to be for the XGP. ‘Mis changes the default o 


spur Mle second name to OXGP. IF/F is 


used, / is done automatically 


8.2.2. Subtitles 


Subtitles can be used by ine 


uding STRINGs in an input file which begin with the word SUBTITLE. The 
remainder of the STRING will be used as part of the header of cach output page until another subtitle is 


found, ‘The STRING need not be a COMMENT. Subtitles may have a maximum of 79 characters, 


Any file containing subtitles will have a table of contents at the beginning of the listing. 


8.2.3. MAT Definition 
“The facility exists in MAT to cause user specified actions to occur at the time a specific ATOM is about to be 
cross-referenced. ‘The most important use of this is for functions which define wings which the user would 


ike MA‘ to recognize. for example, is function one of whose side-cffects is to SETG one of its arguments. 


When Mar encounters an invocation of the function FOO, where FOO has been defined to MAT, it runs 


code generated by the user's MAY definition for FOO. which causes various actions to be performed. 


Mar definitions are always located in a disk file which Is specified by the /D switch. Fach definition must 
be of the form: 
[name arg! arg? arg3 


5) 


me of the item which is being defined and the args are action specifications as described 


where name's the n 


below. 
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The syntax of a MAT definition is somewhat complex. Rasically, there are wo types of actions which can 
take place: ‘setting’ an ATOM to be equivalent w a specified type (Le. FUNCTION, MACRO, etc.) or 


“cross-referencing’ the ATOM (i.c., making it appear in the cross-reference listing). 


The actual definition for an ATOM isa string of MAT action specifications, one for cs 
Ww that ATOM, For cxample, defining FOO to be 
[FOO SETG SKIP SETG] 


implies at least three arguments to FOO. the first and third of which should be tre: 


‘h argument in a call 


ed as If they were SETGed. 
Thus, if 

<FOO FROB 1 MUMBLE> 
were encountered in an input file, it would be treated as though 


<SETG FROB any> 
<SETG MUMBLE any> 


had been encountered. ‘The symbol table would th 


Point (0 the fine on which the pplication of FOO 
appeared as the location of the definitions of FROB and MUMBLE. 

The following tokens are meaningful action specifications: 
CREF means to cross-reference this ATOM, 


SKIP means to do nothing with this argument (a place holder). 


REST means that the rest of the action spccifications may be repeated for the rest of the arguments, 


name (where name's the name of a MDI. SUBR which causes some action to be routinely performed) means to. 
‘act as though the ATOM had had that SUBR applied to it. For example, SETG will cause MAT to treat the 
item as if a SETG had been performed on it Similarly, MANIFEST will cause MAT to believe it 
MANIFESTed. 


ALSO means to do another thing to this ATOM. Thus, [SETG ALSO MANIFEST] specifics that the argument 
should be treated as though it were both SETGed and MANIFESTed. 


~9' where 2’ are two characters, causes a user defined symbol type to be created. In the cross-reference, this 


will appear as xy in front of the name of the ATOM. 


Any of the preceding tokens may have 1~oblist added. ‘This means that instead of the ATOM being set to 


the specified type, arom! ~odlist will be set. “Thus, for example, 
REST SETG!-FLAGS 


might specify a function which takes a LIST of ATOMs and performs 
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<SETG <INSERT atom <GET FLAGS OBLIST>> any> 


‘on each of them. 


[SPEC xy name] specifies name to be the expansion of xy for purposes of the symbol table. Name cannot 
have spaces in it 


Sine I items to be recognized within a function call are at top level, there is a facility for telling MAT 


to recognize structures. This is done by inserting the correct bracket (which Mat will encounter) around the 


SDECL (which is 


p 
handled internally, however) might be 
REST (REST GDECL) SKIP 


Ft of the action specification referring to a structure. For example, a definition for 


which specifies that the arguments are alternately a LIST of things to GDECL and an argument which is 


unimportant 


A special case of bracketing is when the location of the structure is not known. In this case, bracker! 


means ‘find the next object that starts with this bracket’. An example later demonstrates this. 


What follows are some examples from a real definition file. 
[NEWSTRUC NEWTYPE SKIP REST SETG SKIP] 
NEWSTRUC takes an ATOM which becomes the name of a NEWTYPE, the DECL for that TYPE (which is not 
interesting to MA) and an arbitrary number of pairs of ATOMS (names of offeets in the structure) and their 
DECLs (again, not interesting). 
[FLAGWORD REST SETG] 
FLAGMORO takes an arbitrary number of ATOMS and SETGs them something. 
[SPEC PG Pure-Gval] 
[SPEC 08 Object] 
[SPEC AC Action] 
[SPEC V8 Verb} 
[SPEC 0S Object-Synonym: 
[SPEC AD Adjective] 
These define the long descriptions for the newly defined symbol types created in the examples. 
[PSETG =PG] 
PSETG takes an ATOM and a valuc and SETGs the ATOM (also putting it in a LIST of ATOMS to purify). 
[GET-083 “CREF™} 


GET-OBJ takes a STRING PRANE of an object and returns the object. This definition allows “object” to be 


sd here. Note that CREF is in quotes because the element being dealt with 
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[OBIECT [*=08" REST *=05-} EREST “=A0"1) 
OBSECT creates objects which are referenced by GET-083. OBJECT fit tkes a VECTOR of STRINGS the 
firs of which isthe true objet specie (08) ard the rest of which are synonyms (OS). The second argument 
| isa VECTOR of STRINGs, w 
(ADD-ACTION *ACt-ACTIONS" 

A0D-ACTION er 
ACTIONS wo 


ich are PNAMEs of adjectives referring to the object (AD). 
SKIP REST [[1!7=VB!-WORDS" SKIP}}} 
tes ‘verbs’. The name of the verb is the firs 


rgument, which Is a STRING, ADD-ACTION 


SETGS ring! Of type ACTION (AC). ‘The second argument is not interesting, The rest 


ofthe 


iMguments are VECTORS, somewhere in which is a VECTOR of a STRING and an unintere 


ing object. 
ADD-ACTION SETGs this latter STRING (the PNAME of an ATOM in the WORDS OBLIST) to something of 
type verb (VB). ‘This is about as complic: 


sd as a MAT type specification is likely to get 
[1ADD-ACTION "=AC!-ACTIONS ALSO =VB!-WORDS"] 

TADD-ACT ION takes as its first argument a STRING which is SETGed both in the ACTIONS OBLIST and in 

the WORDS OBLIST, to.an ACTION (AC) a 


1d a verb (VB), respectively 


8.2.4. MAT Record Files 


Listing Record (or LREC) files, akin to 


LREC files, can be produced in MAT by including files in the Jel 
ine. Use of an LREC file has the advantage that future invocations of MAT using it need only output the 
changed pages of the listing. The LREC file produced will be placed in file and con 


information, so that fi 


ns all relevant jet 


re calls to MAT for comparison listings need only have file 


in the jel line, Additional 
Jel may then be appended. ‘There is, however, no way to tum off flags once set up. ‘Therefore, if a 


cross-reference file is to be used only occasionally, leaving the cross-reference (/C) flag off for the initial 


ding and appending it at other times is preferable. 


‘An alternate way of creating a Listing Record file is to use /R which is equivalent to 
| inpur-file-first-file-name LREC= 


| in the Jet. Obviously, /® is not sufficient for future comparisons. 


8.3. The MDL-IPC Device Interface MUDINQ 


MubINQ is a small program that formulates, sends, cS messages to and from Mii aver the ITS 


IC CInterprocess Communication’) device. ‘The user specifies a target MID. process by its uname and jname, 

cither on the jel line or tw MUDING directly. He then inputs the messige to be sent to that MDI. ‘The message 
| sent is enclosed in an invisible protective shield (an ERROR handler and so forth) to prevent it from 
Interfering in the operation of the target. ‘The message is PARSEd and EVALed by the target, and the result 
putin a file which is printed by MUDING when it appears. 
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The most common use of this program is to answer the question “What could my compilation (or 
whatever) be doing after all this time? ‘The answer may be obtained by MUDINQing a <FR&> or <F RAMES> 


mpilation is such a common use of MUDING that there is an alias of it, 


Inquiring after the state of ac 


STATUS, which MUDINOS a <STATUS> (sce section 5.1.1) at a compiler process and waits for a response. 


led WHOM lists those MDI. jobs listening on the IPC device. 


Finally, an alias of MUDING calk 


For more details on the operation of the MDI. IPC interface, sec [3} 
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